Payment Requests Callback

📘

Postman Integration

[](https://app.getpostman.com/run-collection/6a95fc3796f1fa3105d1?action=collection%2Fimport#?env%5BCoins%20Asia%20PH%20(Staging)

Payment requests use invoices to track whether the request is already paid or not. These invoices emit events that may be useful to update the status of an item attached to a payment request. Once the customer sends payment for the payment request, an event will be triggered to the merchant's specified callback URL. The merchant's system can then react accordingly based on the triggered event.

How Payment Requests use Invoices

A particular payment request is related to an invoice as denoted by invoice in the payment request's properties. For example, here's a response payload after creating a payment request:

{
    "payment-request": {
        "id": "5edc263fac7f4f61b87632cb5710050f",
        "invoice": "5713e3ab76e74e6b85194deaf0f14cel",
        "payer_contact_info": "[email protected]",
        "payer_contact_info_type": "email",
        "payer_email": "[email protected]",
        "amount": "20.00000000",
        "currency": "PHP",
        "message": "Thanks for all the fish!",
        "message_scope": "private",
        "status": "pending",
        "receiving_account": "5411c4604c9b45b8b74837c84daa0f4c",
        "payment_url": "https://coins.ph/payment/request/5edc263fac7f4f61b87632cb5710050f",
        "created_at": "2016-03-04T07:12:00.352338Z",
        "updated_at": "2016-03-04T07:12:00.474500Z",
        "expires_at":"2017-03-04T07:11:59.942484Z"
    }
}

This payment request uses the invoice 5713e3ab76e74e6b85194deaf0f14cel to track payment events. This means that when you receive an event callback, you should be checking for the invoice id instead of the payment request id in the request payload that will be sent to your endpoint.

Defining a callback URL

A callback URL is an endpoint that accepts a POST request with Content-Type: application/json. Here's an example of a callback URL:

Merchants are free to decide how they would name or nest their callback URL. To assign a designated URL to your application, please see the Merchant Getting Started Guide. A payload delivered to this URL follows this convention:

{
  "event": {
    "name": "invoice.name",
    "data": {
        "id": "invoice_id",
        "currency": "PHP",
        "amount": "100",
        "amount_received": "0",
        "external_transaction_id": "1"
        }
    }
}

Payload Description

• name: The name of the invoice event that occurred. Events are further described in the table that follows after this section.
• data: Contains properties that are specific to the particular event that triggered.
• id: Unique invoice identifier. This is the invoice related to the payment request.
• currency: The currency of the amount.
• amount: The amount of the transaction.
• amount_received: The amount already received as payment for the transaction.
• external_transaction_id: An identifier provided by the merchant during the creation of the transaction. This identifier usually represents an item in the merchant's system.

Events which may be consumed by callbacks are described at the following table:

Authorization

Callbacks strictly require an HTTPS endpoint with a valid SSL certificate. This simplifies the authentication mechanism used by the callback, which is a shared secret contained in the request header sent to your endpoint: Authorization: Token MERCHANT_API_TOKEN. You should check if the MERCHANT_API_TOKEN is the same as the one defined in your dashboard. If it differs, it means that the request is not from an authorized source. This also means that you should not share your MERCHANT_API_TOKEN to prevent unauthorized sources from sending fake callback events.