> For the complete documentation index, see [llms.txt](https://docs.payengine.co/payengine-api-v2.5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payengine.co/payengine-api-v2.5/transactions/credit.md).

# Credit

This API can be used to issue credit to a card.

<mark style="color:green;">`POST`</mark> `https://<Platform-host>/api/payment/credit`

#### Request Body

<table><thead><tr><th width="225.13671875">Name</th><th width="96.1044921875">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>The Transaction/Payment UUID of the original transaction to which the credit should be applied</td></tr><tr><td>data.transaction_amount<mark style="color:red;">*</mark></td><td>string</td><td>Amount to be returned. Should be less or equal to available transaction amount</td></tr><tr><td>data.card_token</td><td>string</td><td>Card token generated by <a href="/pages/YN9W4Ldyth3zlYUEy6qa">Platform secure field API</a></td></tr><tr><td>data.description</td><td>string</td><td>Transaction description. Character limit is 255</td></tr><tr><td>data.metadata</td><td>string</td><td>Add any additional metadata by passing a json object</td></tr><tr><td>data.gateway_id</td><td>string</td><td>Gateway ID (optional, if multigateway mode enabled)</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Field Definitions" %}

<table><thead><tr><th width="159.6279296875">Field Name</th><th width="129.7802734375">Type</th><th width="256.7548828125">Description</th><th>Required?</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Platform payment ID for the sale request</td><td>Required</td></tr><tr><td>transaction_id</td><td>string</td><td>Unique transaction ID</td><td>Required</td></tr><tr><td>gateway_id</td><td>string</td><td>ID of the gateway through which the transaction is processed.</td><td>Optional</td></tr><tr><td>merchant_id</td><td>string</td><td>Merchant ID</td><td>Required</td></tr><tr><td>description</td><td>string</td><td>Transaction description provided in the request</td><td>Optional</td></tr><tr><td>return_response</td><td>object</td><td>Refer to <a href="/pages/K8BP4U8UG9RUhkIFpjn6">Credit Card Sale</a> (SaleResponse)</td><td>Required</td></tr><tr><td>metadata</td><td>object</td><td>Return all the metadata sent in the request</td><td>Optional</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### Sample Request / Response

{% tabs %}
{% tab title="Request Body" %}
**Example Request**

```json
{
    "id": "9a0df7ef-b77f-4525-97e1-f41a98ad7f75",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "metadata": {
            "customer_id": "123",
            "email" : "test@test.com"
        }
    }
}
```

{% endtab %}

{% tab title="Response Body" %}
**Example Response**

```json
{
    "data": {
        "id": "8b321c53-961d-4b52-aced-3039bed0fbc1",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "transaction_id": "668c5d3e-46d4-4a9d-9d17-bc1656ed0227",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "description": "Payment for the services",
        "return_response": {
            "status": "PASS",
            "response_code": "A0000",
            "response_message": "Success",
            "auth_code": "254424",
            "host_response_code": "00",
            "host_reference_number": "751552357011",
            "task_id": "42072951",
            "transaction_id": "57901671",
            "transaction_timestamp": "2025-04-02T19:04:26",
            "transaction_amount": "5.00",
            "processed_amount": "5.00",
            "total_amount": "5.00",
            "address_verification_code": "X",
            "card_holder_verification_code": "N",
            "card_type": "visa",
            "masked_card_number": "1111",
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 07:04 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 57901671      \\nDescription: Payment for the service\\n                 s                  \\n        SUBTOTAL: USD $5.00         \\n          TOTAL: USD $5.00          \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 07:04 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 57901671      \\nDescription: Payment for the service\\n                 s                  \\n        SUBTOTAL: USD $5.00         \\n          TOTAL: USD $5.00          \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "returned_amount": "5.00"
        },
        "metadata": {
            "customer_id": "123",
            "email": "test@test.com"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Webhook event: **PAYMENT\_REFUNDED**
{% endhint %}

#### Webhook Payload Example

```json
{
    "event_uid": "86ecde28452184587aed8084b32c29dd",
    "event": "PAYMENT_REFUNDED",
    "data": {
        "metadata": {
            "email": "test@test.com",
            "customer_id": "123"
        },
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "description": "Payment for the services",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "transaction_id": "3bf3f992-f908-4863-8a7c-575e8ad55ca4",
        "return_response": {
            "status": "PASS",
            "task_id": "46505433",
            "auth_code": "196811",
            "card_type": "visa",
            "total_amount": "5.00",
            "response_code": "A0000",
            "transaction_id": "31472619",
            "returned_amount": "5.00",
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 07:05 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 31472619      \\nDescription: Payment for the service\\n                 s                  \\n        SUBTOTAL: USD $5.00         \\n          TOTAL: USD $5.00          \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 07:05 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 31472619      \\nDescription: Payment for the service\\n                 s                  \\n        SUBTOTAL: USD $5.00         \\n          TOTAL: USD $5.00          \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "processed_amount": "5.00",
            "response_message": "Success",
            "host_response_code": "00",
            "masked_card_number": "1111",
            "transaction_amount": "5.00",
            "host_reference_number": "519296901614",
            "transaction_timestamp": "2025-04-02T19:05:41",
            "address_verification_code": "X",
            "card_holder_verification_code": "N"
        }
    }
}
```