First Party Payment
Overview
For each customer profile, you can generate a unique virtual bank account or PayNow QR for payment collections. When our system successfully receive payments from your users, we will trigger a webhook callback to your system for you to complete the transactions or credit the users for their top-ups.
Sequence Diagram
Create a Virtual Bank Account (VA) or PayNow QR
To accept payments, you have the option to either create a virtual bank account or generate a persistent/dynamic PayNow QR code.
Virtual Bank Account (VA): You can create a virtual bank account to obtain bank transfer details, which you can then provide to your users. This allows users to add a payee in their banking app and complete the transfer.
- SGD VA: This account is created instantly.
- USD VA: Activation typically takes 1 day. StraitsX will send a callback to the URL specified on your StraitsX Business Dashboard once the account status is updated. Note that additional information might be requested, and in some cases, the USD account application may be declined.
PayNow QR: Alternatively, you can also create PayNow QR which you can display to your user for them to easily scan and make transfer.
- Persistent PayNow: You can create a persistent PayNow payment method and provide a QR code to your users. This allows users to make multiple payments using the same QR code. Note that each user can have only one persistent PayNow payment method.
- Dynamic PayNow: You can create a dynamic PayNow payment to generate a unique QR code for each individual transaction. When creating a dynamic PayNow QR code, you need to specify the amount and expiry date. Once a payment is made to a dynamic PayNow QR code, it cannot be used for additional payments.
- Note: Ensure that users do not alter the reference number that is automatically populated after scanning the PayNow QR code, as modifications may result in payment rejection.
Sequence Diagram
Accepting Payment
Once your user make a payment to the VA or PayNow QR provided, StraitsX will send a callback notification to you via the callback URL indicated on the StraitsX Business Dashboard. Learn more about callback configuration.
In the event that a payment is blocked by StraitsX, a callback will be fired to you with the blocked code. In some cases, supplementary information or proof may be required to continue processing the payment. Once the first payment is completed, the customer profile bank account will be verified automatically.
Note: If a payment is less than the transaction fees charged, no amount will be credited to your account.
Sandbox Testing
To test your integration, you could initiate a mock bank transfer or mock PayNow payment. Callback will also be sent in the sandbox environment.
Webhooks
Webhook callbacks use HTTP POST
request with the event in string format and expects 200 OK in the response. Each failed webhook callback is retried up to 20 times with a 5-minute interval. If you need to retrigger callback for a single contract or a list of contracts, you can do so via our callback event endpoints.
For incoming payments, a sample webhook callback looks like the following:
amount=0.01&bank_account_no=3225300696000&blocked_reasons%5B%5D%5Bcode%5D=NM-001&created_at=2024-06-03T07%3A28%3A09.908Z¤cy=xsgd&customer_profile_id=customer_profile_6972bb6a-2a5f-48dd-8ea7-2e07c50e94b3&end_to_end_ref=Transfer&fees=0.01&id=contract_d176576dfb1a498ead53d2b5f77e4122&idempotency_id=SUBSCRIPTION_0cd2163dc32dfdb76250db29f58da2ec&merchant_ref=ref_0d1w4m0xepp40&sender_bank=DBS+Bank+Ltd&sender_bank_account_holder_name=JOHN+DOE&sender_bank_account_no=01234567&sender_bank_swift_bic=DBSSSGSGXXX&status=pending&transaction_remarks=abc&type=Direct+bank+transfer
Parameter Name | Description | Example Value |
---|---|---|
amount | Amount transferred | 0.01 |
bank_account_no | Virtual account number receiving the payment | 3225300696000 |
blocked_reasons | Reason for the transaction being blocked (if any) | [{"code":"NM-001"}] |
created_at | Transaction created time | 2024-06-03T07%3A28%3A09.908Z |
currency | Transaction currency | xsgd |
customer_profile_id | Customer profile ID | customer_profile_6972bb6a-2a5f-48dd-8ea7-2e07c50e94b3 |
end_to_end_ref | Sender's transaction remarks | Transfer |
fees | Fees incurred | 0.01 |
id | Contract ID | contract_d176576dfb1a498ead53d2b5f77e4122 |
idempotency_id | Unique reference no | SUBSCRIPTION_0cd2163dc32dfdb76250db29f58da2ec |
merchant_ref | Unique referenceId indicated in Create a virtual bank account | ref_0d1w4m0xepp40 |
sender_bank | Sender's bank | DBS+Bank+Ltd |
sender_bank_account_holder_name | Sender's name | JOHN+DOE |
sender_bank_account_no | Sender's bank account no | 01234567 |
sender_bank_swift_bic | Sender's bank SWIFT (if available) | DBSSSGSGXXX |
status | Transaction Status | pending |
transaction_remarks | Transaction Remarks | abc |
type | Type of transaction | Direct+bank+transfer |
Updated 2 months ago
Next, learn how to create a payout to facilitate your user's withdrawal requests.