API Reference

• PAYMENTS
  • Process payments
    • postGet Hosted Payment Page URL
    • postCreate payment
    • postVoid payment
    • postRefund payment
  • Retrieve payments
    • getGet payment information by Session ID
    • getGet transaction by ID
  • User-Agent Header
• WEBHOOKS
  • Payment notifications
    • Eventpayment
    • Eventrefund
    • Eventvoid

API docs by Redocly

OxPay Payments API Reference (v1)

Download OpenAPI specification:Download

Process payments

Initiate new payments, void/cancel payments, and process refund payments.

Additionally, /payment-page endpoint allows you to initialize a new payments through hosted payment page, ensuring seamless integration for online transactions.

Get Hosted Payment Page URL

Provide the necessary information of your payment and you will receive an unique URL where you can redirect to our Hosted Payment Page.

Do note that your terminal must be enabled with 'Ecommerce' feature for this endpoint.

Authorizations:

(Bearer TokenSignature)

Request Body schema: application/json

merchant_id required	string = 9 characters Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)
terminal_id required	string = 14 characters Unique identifier for the Terminal. (This will be provided to you upon successful onboarding.)
merchant_reference_id required	string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)
description required	string A short description for the payment transaction.
success_url required	string The URL that will be redirected to after the payment is successfully completed.
failure_url required	string The URL that will be redirected to after the payment failed to complete.
notification_url required	string The URL that will receive the webhook call on payment status updates.
required	object This object contains the transaction amount information.
value required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.
required	object This object contains the transaction source information.
name required string <= 100 characters Name of the payer. email required string <= 254 characters Email address of the payer. phone required string <= 16 characters Mobile number of the payer.
capture	boolean Card only. Optional for sale. Set false for pre-auth.

Responses

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
oxpay_hpp_url required string <= 2048 characters The unique URL with session_id, for the Frontend Appllication to re-direct to the hosted page for payment processing.

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/payment-page

Sandbox Server

https://api.uat.oxpayfinancial.com/payment-page

Request samples

• Payload

Content type

application/json

{

• "merchant_id": "100000001",
• "terminal_id": "10000000000001",
• "merchant_reference_id": "789",
• "description": "Testing",
• "success_url": "http://example.com/success",
• "failure_url": "http://example.com/failure",
• "notification_url": "http://example.com/notify",
• "amount": {

  • "value": 200,
  • "currency": "SGD"

  },
• "source": {

  • "name": "Sarah",
  • "email": "sarah@example.com",
  • "phone": "12345678"

  },
• "capture": true

}

Response samples

• 200
• 400

Content type

application/json

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240103101433"

  },
• "body": {

  • "oxpay_hpp_url": "https://hostedPage/?session_id=123123123123"

  }

}

Create payment

Initiate a new payment transaction. The request payload will vary depending on the brand specified under the payment_method.

The outcome of your request will be communicated asynchronously via payment webhook.

Authorizations:

(Bearer TokenSignature)

Request Body schema: application/json

merchant_id required	string = 9 characters Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)
terminal_id required	string = 14 characters Unique identifier for the Terminal. (This will be provided to you upon successful onboarding.)
merchant_reference_id required	string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)
oxpay_session_id	string >= 50 characters An unique session identifier obtained from /payment-page endpoint.
success_url required	string Success URL to be redirected to after a successful payment.
failure_url required	string Failure URL to redirect to after a failed payment.
notification_url required	string Notify URL to receive the webhook call on payment status updates.
required	object This object contains the transaction amount information.
value required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.
required	object This field contains information of the payment method.
brand string This field is not required. alipayatomedashgrabpaypaynowshopeepaywechatcardcard required object This field contains the information of card. name required string <= 100 characters Name of the payer. card_number required string <= 16 characters Card number of the payer. expiry_month required string <= 2 characters Expiry month of the card. expiry_year required string <= 4 characters Expiry year of the card. cvv required string <= 4 characters CVV of the card. capture boolean Card only. Optional for sale. Set false for pre-auth.

Responses

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
payment_brand string This field is not required. alipayatomedashgrabpaypaynowshopeepaywechatcardcard oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/payment

Sandbox Server

https://api.uat.oxpayfinancial.com/payment

Request samples

• Payload

Content type

application/json

Example

CardAlipayAtomeDashGrabPay (MPQR)GrabPay (CPQR)GrabPay OnlinePaynowShopeePayWechatCard

{

• "merchant_id": "100000001",
• "terminal_id": "10000000000001",
• "merchant_reference_id": "789",
• "oxpay_session_id": "123123123123",
• "success_url": "https://example.com/success",
• "failure_url": "https://example.com/failure",
• "notification_url": "http://example.com/notify",
• "payment_method": {

  • "card_info": {

    • "name": "Sarah",
    • "card_number": "1234567890123456",
    • "expiry_month": "12",
    • "expiry_year": "2025",
    • "cvv": "123"

    },
  • "capture": true

  },
• "amount": {

  • "currency": "SGD",
  • "value": 200

  }

}

Response samples

• 200
• 400

Content type

application/json

Example

CardAlipayAtomeDashGrabpayPaynowShopeePayWechatCard

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20231226021040"

  },
• "body": {

  • "oxpay_txn_id": "10027260",
  • "merchant_reference_id": "1704443543098"

  }

}

Void payment

Void a completed sale transaction or cancel a pending QR transaction.

The outcome of your request will be communicated asynchronously via void webhook.

Authorizations:

(Bearer TokenSignature)

Request Body schema: application/json

merchant_id required	string = 9 characters Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)
terminal_id required	string = 14 characters Unique identifier for the Terminal. (This will be provided to you upon successful onboarding.)
oxpay_original_txn_id required	string Unique Transaction ID of the interested Transaction to be processed with.
merchant_reference_id required	string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)
notification_url required	string The URL that will receive the webhook call on payment status updates.
required	object This field contains the transaction amount information.
value required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.

Responses

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
oxpay_original_txn_id required string Unique Transaction ID of the interested Transaction to be processed with. oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) payment_brand string This field is not required. alipayatomedashgrabpaypaynowshopeepaywechatcardcard transaction_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100)

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/void

Sandbox Server

https://api.uat.oxpayfinancial.com/void

Request samples

• Payload

Content type

application/json

{

• "merchant_id": "100000001",
• "terminal_id": "10000000000001",
• "oxpay_original_txn_id": "1000002",
• "merchant_reference_id": "789",
• "notification_url": "http://example.com/notify",
• "amount": {

  • "value": 200,
  • "currency": "SGD"

  }

}

Response samples

• 200
• 400

Content type

application/json

Example

CardAlipayAtomeDashGrabPayPaynowShopeePayWechatCard

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240103101433"

  },
• "body": {

  • "oxpay_original_txn_id": "1000001",
  • "oxpay_txn_id": "1000002",
  • "merchant_reference_id": "789",
  • "transaction_amount": 200

  }

}

Refund payment

To initiate a refund of a successful sale transaction. The result of your request will be delivered asynchronously through refund webhook.

Authorizations:

(Bearer TokenSignature)

Request Body schema: application/json

merchant_id required	string = 9 characters Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)
terminal_id required	string = 14 characters Unique identifier for the Terminal. (This will be provided to you upon successful onboarding.)
oxpay_original_txn_id required	string Unique Transaction ID of the interested Transaction to be processed with.
merchant_reference_id required	string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)
notification_url required	string The URL that will receive the webhook call on payment status updates.
required	object This field contains the transaction amount information.
value required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.

Responses

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
oxpay_original_txn_id required string Unique Transaction ID of the interested Transaction to be processed with. oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) payment_brand string This field is not required. alipayatomedashgrabpaypaynowshopeepaywechatcardcard refund_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100)

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/refund

Sandbox Server

https://api.uat.oxpayfinancial.com/refund

Request samples

• Payload

Content type

application/json

{

• "merchant_id": "100000001",
• "terminal_id": "10000000000001",
• "oxpay_original_txn_id": "1000002",
• "merchant_reference_id": "789",
• "notification_url": "http://example.com/notify",
• "amount": {

  • "value": 200,
  • "currency": "SGD"

  }

}

Response samples

• 200
• 400

Content type

application/json

Example

CardAlipayAtomeDashGrabpayPaynowShopeePayWechatCard

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240103101433"

  },
• "body": {

  • "oxpay_original_txn_id": "1000001",
  • "oxpay_txn_id": "1000002",
  • "merchant_reference_id": "789",
  • "refund_amount": 200

  }

}

Retrieve payments

Get payment information by Session ID

Retrieve the payment information, including a list of available payment brand.

Do note that each session id has an expiry time associated to it. Once the session id is expired, you will need to request for a new session id via /payment-page endpoint.

Authorizations:

Bearer Token

path Parameters

session_id required

string (OxpaySessionId) >= 50 characters An unique session identifier obtained from /payment-page endpoint.

Responses

Response Schema: application/json

merchant_id required	string = 9 characters Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)
merchant_name required	string Merchant's name. Applicable to digital e-commerce stores and physical stores.
terminal_id required	string = 14 characters Unique identifier for the Terminal. (This will be provided to you upon successful onboarding.)
transaction_id	string Unique Transaction ID auto-generated by OxPay upon processing your request successfully.
expiry_datetime required	string <date-time> The expiry time for Session ID.
merchant_reference_id required	string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.)
transaction_currency required	string = 3 characters Currency in three letter code ISO 4217-Alpha 3.
transaction_amount required	number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100)
description required	string A short description for payment transaction.
payer_name required	string <= 100 characters Name of the payer.
payer_email required	string <= 254 characters Email address of the payer.
payer_phone required	string <= 16 characters Mobile number of the payer.
payer_return_url required	string Merchant's Success URL to be redirected to after a successful payment.
payer_error_url required	string Merchant's Failure URL to redirect to after a failed payment.
payer_notification_url required	string Merchant's Notify URL to receive the webhook call on payment status updates.
payer_capture required	boolean Card only. Optional for sale. Set false for pre-auth.
required	Array of objects (PaymentBrand) List of payment brand.
Array brand_name required string Enum: "Alipay" "Atome" "Card" "Dash" "GrabPay" "Paynow" "ShopeePay" "Wechat" The brand name of the payment method. method_name required string Enum: "CARD" "QR"

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/payment?session_id={session_id}

Sandbox Server

https://api.uat.oxpayfinancial.com/payment?session_id={session_id}

Response samples

• 200
• 400

Content type

application/json

{

• "merchant_id": "100000001",
• "merchant_name": "ABCD Bakery Bishan Outlet",
• "terminal_id": "10000000000001",
• "transaction_id": null,
• "expiry_datetime": "2024-01-18T05:19:23+0000",
• "merchant_reference_id": "1705551757166",
• "transaction_currency": "SGD",
• "transaction_amount": 200,
• "description": "Testing",
• "payer_name": "Sarah",
• "payer_email": "sarah@example.com",
• "payer_phone": "987654321",
• "payer_return_url": "https://example.com/success",
• "payer_error_url": "https://example.com/error",
• "payer_notification_url": "https://example.com/notify",
• "payer_capture": false,
• "payment_brand_list": [

  • {

    • "brand_name": "GrabPay",
    • "method_name": "QR"

    }

  ]

}

Get transaction by ID

Retrieve the full information of a payment transaction.

Authorizations:

Bearer Token

path Parameters

oxpay_txn_id required

string (OxpayTxnId) Unique Transaction ID auto-generated by OxPay upon processing your request successfully.

Responses

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	any OxPay's custom payload body containing transaction information.
oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) host_txn_id required string An unique reference generated by the Acquirer to identify the different payment operation. transaction_state required string Enum: "authorized" "capture_rejected" "capture_submitted" "captured" "error" "pending" "refunded" "rejected" "requested" "sale" "success" "voided" The state of the transaction. payment_brand required string The brand of the payment method. alipayatomedashgrabpaypaynowshopeepaywechatcardcard transaction_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) transaction_currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.

Response Schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing transaction information.
status required string Indicates the status message of the payment request. status_desc required string A short description of the payment status.

Live Server

https://api.oxpayfinancial.com/payment/{oxpay_txn_id}

Sandbox Server

https://api.uat.oxpayfinancial.com/payment/{oxpay_txn_id}

Response samples

• 200
• 400

Content type

application/json

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240103101433"

  },
• "body": {

  • "oxpay_txn_id": "1000001",
  • "merchant_reference_id": "789",
  • "host_txn_id": "cd5e8e33ead44abba444e6e9c736f036",
  • "transaction_state": "pending",
  • "payment_brand": "GrabPay",
  • "transaction_amount": 200,
  • "transaction_currency": "SGD"

  }

}

User-Agent Header

User-Agent Header Required: Please ensure that you include a User-Agent header in all your API requests. This helps us provide better support and analytics.

Syntax: User-Agent: <product> / <product-version> <comment>

Example: User-Agent: MyApp/1.0.0 (compatible; OxPay Integration)

Payment notifications

Receive timely notifications about your payments' status where we will post it through the given 'notify_url'.

payment Webhook

A notification will be sent to the notify_url when a sale transaction is processed.

header Parameters

Signature required

string The Signature will be sent along with the webhook callback to make sure the integrity of the payload. Merchants are adviced to validate the payload with the signature using the sign key. You can view and manage your Sign Keys in the OxPay Merchant Portal Please refer to Integrity for the detailed instructions. Example: "signature": "17448b6efe11f0b1e818a1b093282082e94f322fde7b37b058d0ae437ee1c373"

Request Body schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing Sale Transaction Information.
host_txn_id required string An unique reference generated by the Acquirer to identify the different payment operation. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. payment_brand required string The brand name of the payment method. alipaygrabpaygrabpay transaction_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) transaction_currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3. transaction_state required string Enum: "authorized" "capture_rejected" "capture_submitted" "captured" "error" "pending" "refunded" "rejected" "requested" "sale" "success" "voided" The state of the transaction.

Request samples

• Payload

Content type

application/json

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240111071316"

  },
• "body": {

  • "merchant_reference_id": "789",
  • "oxpay_txn_id": "10001396",
  • "host_txn_id": "b8e4c9205a104d97bf7799cc016613bf",
  • "transaction_state": "success",
  • "payment_brand": "GrabPay",
  • "transaction_amount": 100,
  • "transaction_currency": "SGD"

  }

}

refund Webhook

A notification will be sent to the notify_url when a refund transaction is processed.

header Parameters

Signature required

string The Signature will be sent along with the webhook callback to make sure the integrity of the payload. Merchants are adviced to validate the payload with the signature using the sign key. You can view and manage your Sign Keys in the OxPay Merchant Portal Please refer to Integrity for the detailed instructions. Example: "signature": "17448b6efe11f0b1e818a1b093282082e94f322fde7b37b058d0ae437ee1c373"

Request Body schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing Refund Transaction Information
host_txn_id required string An unique reference generated by the Acquirer to identify the different payment operation. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) oxpay_original_txn_id required string Unique Transaction ID of the interested Transaction to be processed with. oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. transaction_state required string Enum: "authorized" "capture_rejected" "capture_submitted" "captured" "error" "pending" "refunded" "rejected" "requested" "sale" "success" "voided" The state of the transaction. payment_brand required string The brand name of the payment method. alipaygrabpaygrabpay refund_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) transaction_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) transaction_currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.

Request samples

• Payload

Content type

application/json

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240111091221"

  },
• "body": {

  • "merchant_reference_id": "789",
  • "oxpay_txn_id": "10001396",
  • "host_txn_id": "1c99a4a93c3c12378a902f4567a50f68",
  • "transaction_state": "refunded",
  • "payment_brand": "GrabPay",
  • "oxpay_original_txn_id": "10001396",
  • "refund_amount": 100,
  • "transaction_amount": 100,
  • "transaction_currency": "SGD"

  }

}

void Webhook

A notification will be sent to the notify_url when a void or cancel transaction is processed.

header Parameters

Signature required

string The Signature will be sent along with the webhook callback to make sure the integrity of the payload. Merchants are adviced to validate the payload with the signature using the sign key. You can view and manage your Sign Keys in the OxPay Merchant Portal Please refer to Integrity for the detailed instructions. Example: "signature": "17448b6efe11f0b1e818a1b093282082e94f322fde7b37b058d0ae437ee1c373"

Request Body schema: application/json

required	object OxPay's custom payload headers containing critical transaction information.
status_code required integer <int32> Indicates the status code of the payment request. See operation status. status_message required string Indicates the status message of the payment request. gateway_response_datetime required string <date-time> Indicates the gateway response datetime of the payment request.
required	object OxPay's custom payload body containing Void Transaction Information
host_txn_id required string An unique reference generated by the Acquirer to identify the different payment operation. merchant_reference_id required string [ 1 .. 100 ] characters Unique identifier or transaction ID provided by you. (Must be unique for each Terminal.) oxpay_txn_id required string Unique Transaction ID auto-generated by OxPay upon processing your request successfully. transaction_state required string Enum: "authorized" "capture_rejected" "capture_submitted" "captured" "error" "pending" "refunded" "rejected" "requested" "sale" "success" "voided" The state of the transaction. payment_brand required string The brand name of the payment method. alipaygrabpaygrabpay transaction_amount required number <integer> >= 1 The transaction amount (Positive integer) in the smallest currency unit, with no decimal point (Example -> SGD 1 = 100) transaction_currency required string = 3 characters Currency in three letter code ISO 4217-Alpha 3.

Request samples

• Payload

Content type

application/json

{

• "headers": {

  • "status_code": 0,
  • "status_message": "SUCCESS",
  • "gateway_response_datetime": "20240111104254"

  },
• "body": {

  • "merchant_reference_id": "789",
  • "oxpay_txn_id": "10001395",
  • "host_txn_id": "3d19976796d64e99a6d780c5r5b927db",
  • "transaction_state": "voided",
  • "payment_brand": "GrabPay",
  • "transaction_amount": 100,
  • "transaction_currency": "SGD"

  }

}