# 2. Initiate Payment (By Key)

## Initiate Payment (Key)

<mark style="color:green;">`POST`</mark> `{{Base Adres}}/api/paywall/apm/pay/bykey`

{% hint style="info" %}
**Important**: To use the APM Payment Initiation service, you need to include the '**apikeypublic**' and '**apiclientpublic**' parameters in the 'Header' section.

\
[<mark style="color:green;">**PaymentAPI Address**</mark>](/payment-orchestration-integration-document/environment.md)
{% endhint %}

**The headers parameters that need to be sent to the service are as follows:**

<table><thead><tr><th width="178">Parameter</th><th width="111.015625">Type</th><th width="146">Compulsory</th><th width="403">Description</th></tr></thead><tbody><tr><td>apikeypublic</td><td>string</td><td>Yes</td><td>The Public Key obtained from the merchant panel.</td></tr><tr><td>apiclientpublic</td><td>string</td><td>Yes</td><td>The Public Client obtained from the merchant panel.</td></tr></tbody></table>

**The parameters that need to be sent to the service in the BODY are as follows:**

<table><thead><tr><th width="240.98828125">Parameter</th><th width="92">Type</th><th width="152.7421875">Compulsory</th><th width="336">Description</th></tr></thead><tbody><tr><td>ApmKey</td><td>string</td><td>Yes</td><td>APM provider key information<br><br>See: <a href="/pages/SBmzwsUcnHQe4CKnuSWt">APM</a></td></tr><tr><td>CurrencyId</td><td>int</td><td>Yes</td><td>Currency in which the payment is requested<br><br>See: <a href="/pages/bahfUMz1dqpN1ZCnpVtM">Currenc</a></td></tr><tr><td>MerchantUniqueCode</td><td>string</td><td>Yes</td><td>Unique number you created for the payment</td></tr><tr><td>MerchantSuccessBackUrl</td><td>string</td><td>Yes</td><td>Address where the successful payment result will be sent receives Post Body response</td></tr><tr><td>MerchantFailBackUrl</td><td>string</td><td>Yes</td><td>Address where the successful payment result will be sent receives Post Body response</td></tr><tr><td>Amount</td><td>decimal</td><td>Yes</td><td>Payment amount<br><br><mark style="color:yellow;">*</mark> <code>If IsRecurring</code> is <mark style="color:$success;">true</mark> this value represents the maximum amount to be charged</td></tr><tr><td>Description</td><td>string</td><td>Yes</td><td>Description of the payment Depending on the provider this description may be displayed on the payment screen</td></tr><tr><td>IsRecurring</td><td>bool</td><td>No</td><td>If the APM provider supports receiving payment instructions this parameter should be sent as true<br><br>Supported Provider <strong>Masterpass</strong></td></tr><tr><td>ExpireDay</td><td>int</td><td>No</td><td>Used if the APM provider supports expiration date on the relevant page or payment flow expects number of days and adds it on top of the current active day<br><br>Supported Provider <strong>Masterpass</strong></td></tr><tr><td>IsAutoCommit</td><td>bool</td><td>No(true)</td><td>By default true value is set if you want to change it it should be set as false<br><br>When true is sent after the 3D process once the payment is completed on the screen the amount is immediately charged from the card</td></tr><tr><td>Payer</td><td><mark style="color:orange;">Payer</mark></td><td>Yes</td><td>When false is sent after the payment a callback is triggered and then a separate commit request must be sent<br><br>Object containing the payer information for the payment<br>The required fields within this object may vary depending on the parameters expected by the provider<br>It is recommended to send all information</td></tr></tbody></table>

#### <mark style="color:orange;">Payer</mark> :

<table><thead><tr><th width="221">Parameter</th><th width="160">Type</th><th width="148">Compulsory</th><th width="336">Description</th></tr></thead><tbody><tr><td>Fullname</td><td>string</td><td>Yes (Conditional)</td><td>Payer full name</td></tr><tr><td>CardNumber</td><td>string</td><td>Yes (Conditional)</td><td>Payer card number (e.g. meal card etc)</td></tr><tr><td>CardId</td><td>string</td><td>Yes (Conditional)</td><td>Payer card identity number works if stored in the APM provider</td></tr><tr><td>Phone</td><td>string</td><td>Yes (Conditional)</td><td>Payer phone number</td></tr><tr><td>Email</td><td>string</td><td>Yes (Conditional)</td><td>Payer email address</td></tr><tr><td>UserIdentity</td><td>string</td><td>Yes (Conditional)</td><td>Payer identity information in your system (TCKN/VKN)</td></tr><tr><td>ConsumerIdentity</td><td>string</td><td>Yes (Conditional)</td><td>Payer identity information in your system (UserId)</td></tr><tr><td>Birthday</td><td>DateTime</td><td>No</td><td>Payer date of birth</td></tr><tr><td>CardAlias</td><td>string</td><td>Yes (Conditional)</td><td>Label of the card belonging to the payer (Masterpass)</td></tr></tbody></table>

**A sample JSON to be sent to the service is as follows**

{% tabs %}
{% tab title="JSON" %}

```json
{
    "ApmKey": "ProviderKey",
    "CurrencyId": 1,
    "MerchantUniqueCode": "TESTMERCHANTUNIQUECODE",
    "MerchantSuccessBackUrl": "https://webhook.site/38a6fa6f-3414-40db-b2a7-a6c38894b6a3",
    "MerchantFailBackUrl": "https://webhook.site/38a6fa6f-3414-40db-b2a7-a6c38894b6a3",
    "Amount": 1,
    "Description": "test",
    "IsRecurring": true,
    "ExpireDay": 10,
    "IsAutoCommit": true,
    "Payer": {
        "Fullname": "",
        "CardNumber": "",
        "CardId": "",
        "Phone": "",
        "Email": "",
        "UserIdentity": "",
        "ConsumerIdentity": "",
        "Birthday": null
    },
    "Products": [
        {
            "ProductId": "123",
            "ProductName": "Name",
            "ProductCategory": "Food",
            "ProductDescription": "Description of Product",
            "ProductAmount": 1
        }
    ]
}
```

{% endtab %}
{% endtabs %}

**The parameters returned from the service are as follows**

<table><thead><tr><th width="189">Parameter</th><th width="100.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>ErrorCode</td><td>int</td><td>Error code returns 0 if the operation is successful</td></tr><tr><td>Result</td><td>bool</td><td>Returns true or false if the operation is successful it returns true</td></tr><tr><td>Message</td><td>string</td><td>If the operation fails this is the message describing the error with language support based on the locale parameter</td></tr><tr><td>Body</td><td>object</td><td>If the operation fails this is the error detail object</td></tr></tbody></table>

{% tabs %}
{% tab title="JSON" %}

```json
{
    "ErrorCode": 0,
    "Result": true,
    "Message": "",
    "Body": {
        "RedirectUrl": "https://dev-payment-agent.itspaywall.com/paywall/callbackapm?UniqueNumber=dd224827-8433-45f7-9454-97025e57fa9e",
        "Transaction": {
            "ApmTransactionId": 29,
            "UniqueCode": "dd224827-8433-45f7-9454-97025e57fa9e",
            "MerchantUniqueCode": "TESTMERCHANTUNIQUECODE",
            "Amount": 1.0
        }
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.paywall.one/payment-orchestration-integration-document/alternative-methods-apm/checkoutpage/2.-initiate-payment-by-key.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.