Skip to main content

API Reference

API docs by Redocly

OxPay Payments API Reference

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 = 6 characters

Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)

terminal_id
required
string = 11 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.

required
object

This object contains the transaction source information.

capture
required
boolean

Indicates whether the payment will be auto-captured. (This is only applicable for Card transaction.)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

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 = 6 characters

Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)

terminal_id
required
string = 11 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.

required
object

This field contains information of the payment method.

Responses

Request samples

Content type
application/json
Example
{
  • "merchant_id": 334567,
  • "terminal_id": 10233456701,
  • "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": {
    },
  • "amount": {
    }
}

Response samples

Content type
application/json
Example
{
  • "headers": {
    },
  • "body": {
    }
}

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 = 6 characters

Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)

terminal_id
required
string = 11 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.

Responses

Request samples

Content type
application/json
{
  • "merchant_id": 101011,
  • "terminal_id": 10110101101,
  • "oxpay_original_txn_id": 1000002,
  • "merchant_reference_id": 789,
  • "notification_url": "http://example.com/notify",
  • "amount": {
    }
}

Response samples

Content type
application/json
Example
{
  • "headers": {
    },
  • "body": {
    }
}

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 = 6 characters

Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)

terminal_id
required
string = 11 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.

Responses

Request samples

Content type
application/json
Example
{
  • "merchant_id": 101011,
  • "terminal_id": 10110101101,
  • "oxpay_original_txn_id": 1000002,
  • "merchant_reference_id": 789,
  • "notification_url": "http://example.com/notify",
  • "amount": {
    }
}

Response samples

Content type
application/json
Example
{
  • "headers": {
    },
  • "body": {
    }
}

Capture payment

Capture a GrabPay Online payment after authorization.

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

Authorizations:
(Bearer TokenSignature)
Request Body schema: application/json
merchant_id
required
string = 6 characters

Unique identifier for the Merchant. (This will be provided to you upon successful onboarding.)

terminal_id
required
string = 11 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.

required
object

This field contains information of the payment method.

code
required
string

The authorization code received from GrabPay

Responses

Request samples

Content type
application/json
{
  • "merchant_id": 334567,
  • "terminal_id": 10233456701,
  • "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",
  • "code": "5ddaab66a1274e92ad606",
  • "payment_method": {
    },
  • "amount": {
    }
}

Response samples

Content type
application/json
{
  • "headers": {
    },
  • "body": {
    }
}

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 samples

Content type
application/json
{
  • "merchant_id": 101011,
  • "merchant_name": "ABCD Bakery Bishan Outlet",
  • "terminal_id": 10110101101,
  • "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": [
    ]
}

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 samples

Content type
application/json
{
  • "headers": {
    },
  • "body": {
    }
}

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.

required
object

OxPay's custom payload body containing Sale Transaction Information.

Request samples

Content type
application/json
{
  • "headers": {
    },
  • "body": {
    }
}

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.

required
object

OxPay's custom payload body containing Refund Transaction Information

Request samples

Content type
application/json
{
  • "headers": {
    },
  • "body": {
    }
}

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.

required
object

OxPay's custom payload body containing Void Transaction Information

Request samples

Content type
application/json
{
  • "headers": {
    },
  • "body": {
    }
}