Merchant Notification Webhooks

Your system can receive HTTP POST notifications (webhooks) from DeficoPay whenever the status of a transaction changes to a final state. These callbacks are used to keep your backend synchronized with transaction statuses in real-time.

When Are Notifications Sent?

A notification is sent when a transaction reaches any of the following final statuses:

completed — Transaction completed successfully

failed — Transaction failed

cancelled — Transaction was cancelled by the user or system

rejected — Transaction was rejected by the PSP

error — Internal or PSP error occurred

expired — Transaction expired (if supported)

The callback URL is specified per transaction in the field:
merchant_notification_url

Callback Request Format

Method: POST

Content-Type: application/json

Signature: Header X-API-Signature (see Request Signing below)

JSON Body Example

{
  "amount": "100.00 USD",
  "currency": "USD",
  "payment_method_code": "paypal",
  "merchant_transaction_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "deficopay_transaction_id": "f1e2d3c4-b5a6-7890-cdef-0987654321ef",
  "status": "completed",
  "order": {
    "id": "ORD-123456",
    "description": "Payment for order #123456"
  },
  "customer": {
    "email": "customer@example.com"
  }
}

Field Reference

Field	Type	Description
amount	string	Transaction amount (formatted with currency, e.g., `"100.00 USD"`)
currency	string	ISO currency code (`USD`, `ARS`, `BRL`, etc.)
payment_method_code	string	Payment method code (e.g., `"paypal"`, `"rapipago_ar"`)
merchant_transaction_id	string	Merchant’s internal transaction ID
deficopay_transaction_id	string	DeficoPay transaction ID
status	string	Final transaction status (`completed`, `failed`, etc.)
order.id	string	Order ID (if provided by merchant)
order.description	string	Order description
customer.email	string	Customer email (if provided)

Status Reference

Possible values for the status field in notifications:

completed

failed

cancelled

rejected

error

expired

Transactions in non-final statuses (such as initiated or pending) do not trigger notifications.

Request Signing

All notifications are signed for security. The header X-API-Signature contains a JWT-based HMAC signature generated using the merchant’s API key.

Header example:
X-API-Signature: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Always verify the signature using your API key before processing the callback!

Idempotency

If your endpoint responds with a non-2xx HTTP status, our system may retry sending the notification multiple times.

Please make your endpoint idempotent.

Acknowledge receipt with HTTP 200 OK.

Example cURL

Handling Callbacks

Verify the request signature.

Parse the JSON payload.

Update the transaction status in your system based on deficopay_transaction_id and status.

FAQ

Q: What if I miss a notification?
A: You can always fetch the current status using the Transaction Status API.

Q: Will I get multiple notifications for the same transaction?
A: Only when the transaction changes status to another final state.

Sample Notification Payloads

Completed

{
  "amount": "100.00 USD",
  "currency": "USD",
  "payment_method_code": "paypal",
  "merchant_transaction_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "deficopay_transaction_id": "f1e2d3c4-b5a6-7890-cdef-0987654321ef",
  "status": "completed",
  "order": {
    "id": "ORD-123456",
    "description": "Payment for order #123456"
  },
  "customer": {
    "email": "customer@example.com"
  }
}

Failed

{
  "amount": "100.00 USD",
  "currency": "USD",
  "payment_method_code": "paypal",
  "merchant_transaction_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "deficopay_transaction_id": "f1e2d3c4-b5a6-7890-cdef-0987654321ef",
  "status": "failed",
  ...
}

Troubleshooting

Make sure your endpoint is publicly accessible.

Allow only requests signed with your API key.

Log all received callbacks for support/debug purposes.

Merchant Notification Webhooks