Overview
Paypoint Online Payment Gateway Service API (V1)
Test endpoint: https://mpqr-test.eftpos.com.sg/
Flows
Flow in Merchant Website and Paypoint.
Authentication
1. Header
Every API request requires the following HTTP headers to be included.
| Header Key | Description |
|---|---|
| Authorization | partner_id:base64_encoded_hmac_signature |
| X-Request-Date | the date of the request as per the format 'YYYY-MM-DDTHH:MM:SS.SSS' |
| Content-Type | the MIME type of the body of the request when present. Eg: "application/json" |
| Accept | the MIME type of the body of the response will present in Payment and Inquiry. |
2. HMAC Signature
Authenticate your account when using the API by computing a HMAC signature. The signature is obtained in 3 steps:
Step. 1: Content Hashing
content_digest = base64.encode(sha256(request_body).digest())
Step. 2: Signing String
The string to be signed is the concatenation of, the order matters, the value of the following:
HTTP Verb: The uppercase HTTP request method e.g. "GET", "POST".
newline: "\n"
Content-Type header: The MIME type of the body of the request. eg. application/json.
newline: "\n"
Date header: as specified above. eg. 2022-07-15T15:21:41.554.
newline: "\n"
URL path with leading slash with request parameters when present: : eg. /api/ecommerce/wallet/v1/otc/pay.
newline: "\n"
Content digest: result string of step 1.
newline: "\n"
The concatenated string, UTF-8 encoded, needs to be signed using the secret. The hash function is again SHA256.
newline: "\n"
Content-Type header: The MIME type of the body of the request. eg. application/json.
newline: "\n"
Date header: as specified above. eg. 2022-07-15T15:21:41.554.
newline: "\n"
URL path with leading slash with request parameters when present: : eg. /api/ecommerce/wallet/v1/otc/pay.
newline: "\n"
Content digest: result string of step 1.
newline: "\n"
hmac_signature = HMAC("SHA256", partner_secret, string_to_sign)
Step. 3: Encoding
base64_encoded_hmac_signature = base64.encode(hmac_signature)
Online Payment Gateway
Initial Payment
Initialize the payment transaction.
REQUEST BODY SCHEMA: application/json
| Field Id | Type | Required | Description |
|---|---|---|---|
| merchant_id | string | Mandatory | Provided by ASCAN. |
| store_id | string | Mandatory | Provided by ASCAN. |
| wallet_name | string | Mandatory | Provided by ASCAN. |
| gateway | string | Optional | Provided by ASCAN. |
| gateway_wallet_name | string | Optional | Provided by ASCAN. |
| transaction_id | string | Mandatory | It is an unique transaction reference. |
| orderId | string | Mandatory | It is an unique order reference. |
| currency | string | Mandatory | Like 'SGD', 'USD' |
| amount | integer | Mandatory | Sale amount with no decimal point. |
| redirectURL | string | Mandatory | Return redirect URL for merchant website. |
| notificationURL | string | Optional | Notification URL for merchant |
RESPONSES:
Request Samples
Payload
Content type
application/json
| { | ||
| "merchant_id": "600054000000384", | ||
| "store_id": "60006371" | ||
| "wallet_name": "ATOME" | ||
| "transaction_id": "1657878693315" | ||
| "orderId": "ORD1657878693315" | ||
| "currency": "SGD" | ||
| "amount": "5000" | ||
| "redirectURL": "http://mpqr-test.eftpos.com.sg:3000/callback" | ||
| "notificationURL": "https://mpqr-test.eftpos.com.sg/app/api/ecommerce/v1/otc/atome/webhook" | ||
| } | ||
Response Samples
200 400 500
Content type
application/json
| { | ||
| "merchant_id": "600054000000384" | ||
| "store_id": "60006371" | ||
| "wallet_name": "ATOME" | ||
| "gateway": "false" | ||
| "gateway_wallet_name": null | ||
| "transaction_id": "1657878693315" | ||
| "orderId": "ORD1657878693315" | ||
| "currency": "SGD" | ||
| "amount": "5000" | ||
| "partnerTxnReference": null | ||
| "redirectUrl": null | ||
| "qrCode": "https://app.apaylater.net/qr/05146751c07a41b5b25a6a5976f3b08f" | ||
| "htmlData": null | ||
| } | ||
Payment Inquiry
Payment Inquiry.
REQUEST BODY SCHEMA: application/json
| Field Id | Type | Required | Description |
|---|---|---|---|
| merchant_id | string | Mandatory | |
| store_id | string | Mandatory | |
| transaction_id | string | Mandatory | Original Transaction reference |
RESPONSES:
Request Samples
Payload
Content type
application/json
| { | ||
| "merchant_id": "600054000000384" | ||
| "store_id": "60006371" | ||
| "transaction_id": "1657878693315" | ||
| } | ||
Response Samples
200 400 500
Content type
application/json
| { | ||
| "merchant_id": "600054000000384" | ||
| "store_id": "60006371" | ||
| "wallet_name": "ATOME" | ||
| "gateway": "false" | ||
| "gateway_wallet_name": null | ||
| "transaction_id": "1657878693315" | ||
| "orderId": "ORD1657878693315" | ||
| "currency": "SGD" | ||
| "amount": "5000" | ||
| "partnerTxnReference": null | ||
| "status": "PROCESSING" | ||
| } | ||
Callback
Online payment acquirer callback (Front channel means browser redirect).
REQUEST PATH PARAMETERS:
| Field Id | Type | Description |
|---|---|---|
| wallet_name | string | Should send wallet name in Path value |
| txn_ref | string | Original Transaction reference |
RESPONSES:
Response Samples
400 500
Content type
application/json
| { | ||
| "error": { "error_code": "Bad_Request", "error_description": "string" }, |
||
| "status": "F" | ||
| } | ||
Webhook
Online payment acquirer webhook (Back channel means acquirer post web hook message to paypoint).
REQUEST PATH PARAMETERS:
| Field Id | Type | Description |
|---|---|---|
| wallet_name | string | Should send wallet name in Path value |
RESPONSES:
Response Samples
400 500
Content type
application/json
| { | ||
| "error": { "error_code": "Bad_Request", "error_description": "string" }, |
||
| "status": "F" | ||
| } | ||