Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Payment webhook notification

Prev Next
Post
/your_payment_webhook_url

Webhook notification that will be sent to your defined webhook url for updates to payment status.

Header parameters
x-callback-token
string

Your Xendit unique webhook token to verify the origin of the webhook. It is highly recommended for your integration to verify this value.

Body parameters

Payment capture status callback

{
  "paymentCapture": {
    "value": {
      "event": "payment.capture",
      "business_id": "6094fa76c2fd53701b8e079c",
      "created": "2021-12-02T14:52:21.566Z",
      "data": {
        "payment_id": "py-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "business_id": "6094fa76c2fd53701b8e079c",
        "status": "SUCCEEDED",
        "payment_request_id": "pr-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "request_amount": 10000,
        "customer_id": "cust-5ed61c4e-499f-49bd-9d90-f3f45028a7a3",
        "channel_code": "BRI_VIRTUAL_ACCOUNT",
        "country": "ID",
        "currency": "IDR",
        "reference_id": "example_reference_id",
        "description": "Payment description",
        "channel_properties": {
          "failure_return_url": "https://xendit.co/failure",
          "success_return_url": "https://xendit.co/success"
        },
        "type": "SINGLE_PAYMENT",
        "created": "2021-12-02T14:52:21.566Z",
        "updated": "2021-12-02T14:52:21.566Z"
      }
    }
  },
  "paymentAuthorization": {
    "value": {
      "event": "payment.authorization",
      "business_id": "6094fa76c2fd53701b8e079c",
      "created": "2021-12-02T14:52:21.566Z",
      "data": {
        "payment_id": "py-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "business_id": "6094fa76c2fd53701b8e079c",
        "status": "AUTHORIZED",
        "payment_request_id": "pr-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "request_amount": 10000,
        "customer_id": "cust-5ed61c4e-499f-49bd-9d90-f3f45028a7a3",
        "channel_code": "CARDS",
        "country": "PH",
        "currency": "PHP",
        "reference_id": "example_reference_id",
        "description": "Payment description",
        "channel_properties": {
          "failure_return_url": "https://xendit.co/failure",
          "success_return_url": "https://xendit.co/success"
        },
        "type": "SINGLE_PAYMENT",
        "created": "2021-12-02T14:52:21.566Z",
        "updated": "2021-12-02T14:52:21.566Z"
      }
    }
  },
  "paymentFailure": {
    "value": {
      "event": "payment.failure",
      "business_id": "6094fa76c2fd53701b8e079c",
      "created": "2021-12-02T14:52:21.566Z",
      "data": {
        "payment_id": "py-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "business_id": "6094fa76c2fd53701b8e079c",
        "status": "FAILED",
        "payment_request_id": "pr-1fdaf346-dd2e-4b6c-b938-124c7167a822",
        "request_amount": 10000,
        "customer_id": "cust-5ed61c4e-499f-49bd-9d90-f3f45028a7a3",
        "channel_code": "CARDS",
        "country": "TH",
        "currency": "THB",
        "reference_id": "example_reference_id",
        "description": "Payment description",
        "failure_code": "INSUFFICIENT_BALANCE",
        "channel_properties": {
          "failure_return_url": "https://xendit.co/failure",
          "success_return_url": "https://xendit.co/success"
        },
        "type": "SINGLE_PAYMENT",
        "created": "2021-12-02T14:52:21.566Z",
        "updated": "2021-12-02T14:52:21.566Z"
      }
    }
  }
}
Expand All
object

Payment capture status callback for payment

event
string

Webhook event names for payment capture status updates.

Valid values[ "payment.capture", "payment.authorization", "payment.failure" ]
business_id
string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8
created
string (date-time)

Timestamp of webhook delivery attempt in ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
data
object (Payments_API_PaymentSchema)

Payment object

payment_id
string

Xendit unique Payment ID generated as reference for a payment.

Examplepy-1402feb0-bb79-47ae-9d1e-e69394d3949c
business_id
string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8
reference_id
string

A Reference ID from merchants to identify their request.

Min length1
Max length255
payment_request_id
string

Xendit unique Payment Request ID generated as reference after creation of payment request.

Examplepr-1102feb0-bb79-47ae-9d1e-e69394d3949c
payment_token_id
string

Xendit unique Payment Token ID generated as reference for reusable payment details of the end user.

Examplept-cc3938dc-c2a5-43c4-89d7-7570793348c2
customer_id
string

Xendit unique Capture ID generated as reference for the end user

Max length41
Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48
type
string

The payment collection intent type for the payment request.

PAY: Create a payment request that is able to receive one payment.

PAY_AND_SAVE: Create a payment request that is able to receive one payment. If the payment is successful, a reusable payment token will be returned for subsequent payment requests.

REUSABLE_PAYMENT_CODE: Create a payment request that is able to receive multiple payments. This is only used for repeat use payment method like a static QR, a predefined OTC payment code or a predefined Virtual Account number.

Valid values[ "PAY", "PAY_AND_SAVE", "REUSABLE_PAYMENT_CODE" ]
country
string

ISO 3166-1 alpha-2 two-letter country code for the country of transaction.

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY" ]
ExampleID
currency
string

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD" ]
ExampleIDR
request_amount
number

The intended payment amount to be collected from the end user.

Minimum0.0
Example10000
capture_method
string

AUTOMATIC: payment capture will be processed immediately after payment request is created. MANUAL: payment capture requires merchant's trigger via payment capture endpoint before being processed

Valid values[ "AUTOMATIC", "MANUAL" ]
Default"AUTOMATIC"
ExampleAUTOMATIC
channel_code
string

Channel code used to select the payment method provider. Use routing payment channels mapping for full list of channel codes.

captures
Array of object (Payments_API_Capture)
object

Capture object contains information about the capture that was performed

capture_timestamp
string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
capture_id
string

Xendit unique Capture ID generated as reference for a single capture.

Examplecap-1502feb0-bb79-47ae-9d1e-e69394d3949c
capture_amount
number

The payment amount captured for this payment. Maximum capture amount can only be equal or lesser than the authorized amount value.

Minimum0.0
Example10000
status
string

Status of the payment.

Valid values[ "AUTHORIZED", "CANCELED", "SUCCEEDED", "FAILED", "EXPIRED", "PENDING" ]
ExampleSUCCEEDED
payment_details
object (Payments_API_PaymentDetails)

Payment information provided by the payment method provider. Fields returned are dependent on what is made available by the provider.

authorization_data
object (Payments_API_AuthorizationData)

Specific to cards transaction only. Details about the card authorization processing.

authorization_code
string

Authorization approval code from the scheme. 6 alphanumeric characters.

cvn_verification_result
string

Whether CVN input matches with the issuer's data.

Valid values[ "M", "N" ]
address_verification_result
string

Whether the end user's address input matches with the issuer's data.

Valid values[ "M", "N" ]
retrieval_reference_number
string

Receipt reference number communicated to the end user by their card issuer for this specific payment. This a commonly used reference number for the end users to raise tickets.

network_response_code
string

The response code returned by the scheme (Visa, Mastercard, JCB, China Unionpay or Amex).

network_response_code_descriptor
string

Description of the response code.

network_transaction_id
string

Transaction ID received from the card scheme. Only available for merchants on switcher model.

acquirer_merchant_id
string

Acquirer's record of the MID that was used to process this transaction. Only available for merchants on switcher model.

reconciliation_id
string

Acquirer's transaction record of the payment on their settlement statement. Only available for merchants on switcher model.

authentication_data
object (Payments_API_AuthenticationData)

Specific to cards transaction only. Details about the card authentication.

flow
string

Indicates the flow that was used for the 3DS authentication.

Valid values[ "FULL_AUTH", "FRICTIONLESS" ]
a_res
object

Details about the card authentication response from the 3DS server.

eci
string

Payment system-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

message_version
string

The 3DS protocol version which has been used to perform 3DS.

authentication_value
string

The result value from the 3DS transaction received from the ACS. This value is no longer present on responses after 45 days have passed after the authentication. Note that Mastercard and Visa use a different underlying format.

ds_trans_id
string

Universally unique transaction identifier assigned by the DS to identify a single transaction.

issuer_name
string

Name of the payment method provider used by the end user.

sender_account_number
string

Account number of the end user making the payment from the payment method provider's records.

sender_name
string

Name of the end user making the payment from the payment method provider's records.

receipt_id
string

Receipt reference number communicated to the end user by their payment method provider for this specific payment. This a commonly used reference number for the end users to raise tickets.

remark
string

Remarks about this specific payment from the payment method provider's records.

network
string

Payment network which the payment was processed over.

fund_source
string

Information about what was used by the end user to complete the payment. e.g. balance, installment, credit.

failure_code
string

Failure codes for payments.

Valid values[ "ACCOUNT_ACCESS_BLOCKED", "INVALID_MERCHANT_SETTINGS", "INVALID_ACCOUNT_DETAILS", "PAYMENT_ATTEMPT_COUNTS_EXCEEDED", "USER_DEVICE_UNREACHABLE", "CHANNEL_UNAVAILABLE", "INSUFFICIENT_BALANCE", "ACCOUNT_NOT_ACTIVATED", "INVALID_TOKEN", "SERVER_ERROR", "PARTNER_TIMEOUT_ERROR", "TIMEOUT_ERROR", "USER_DECLINED_PAYMENT", "USER_DID_NOT_AUTHORIZE", "PAYMENT_REQUEST_EXPIRED", "FAILURE_DETAILS_UNAVAILABLE", "EXPIRED_OTP", "INVALID_OTP", "PAYMENT_AMOUNT_LIMITS_EXCEEDED", "OTP_ATTEMPT_COUNTS_EXCEEDED", "CARD_DECLINED", "DECLINED_BY_ISSUER", "ISSUER_UNAVAILABLE", "INVALID_CVV", "DECLINED_BY_PROCESSOR", "CAPTURE_AMOUNT_EXCEEDED ", "AUTHENTICATION_FAILED" ]
ExampleCARD_DECLINED
metadata
object (Payments_API_MerchantMetadata)

Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }
created
string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
updated
string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
Responses
200

OK