Overview
This document is for contracted merchants only. Do not publish or redistribute it.
Transaction types
ST Pay offers two types of transactions. Both are created by your server through the API:
| Transaction | Flow of funds | Process |
|---|---|---|
| Collection | Payer → ST Pay receiving account → Your ST Pay balance | You create a collection order and receive the receiving account number and the payable amount, then ask the payer to make the transfer. Once ST Pay confirms that the payment has been credited, the settlement amount (after the fee is deducted) is added to your balance, and ST Pay notifies you by Callback. |
| Payout | Your ST Pay balance → Payee | You create a payout order and specify the payee's account number. After ST Pay pays out, the payout amount plus the fee is deducted from your balance, and ST Pay notifies you by Callback. |
Two channels are supported: fps (FPS, Faster Payment System) and bank_transfer (bank transfer).
API overview
| API | Purpose | Method and path |
|---|---|---|
| Create a collection order | Create a collection order and get the payment details | POST /api/v1/collect/orders |
| Create a payout order | Create a payout order | POST /api/v1/payout/orders |
| Query a collection order | Get the current status and amounts of a collection order | POST /api/v1/collect/orders/query |
| Query a payout order | Get the current status and amounts of a payout order | POST /api/v1/payout/orders/query |
| Callback | ST Pay notifies you when an order has a result | ST Pay sends a POST to the callback_url you sent when creating the order |
Integration process
- Provide the following to ST Pay
- Server egress IPs: every source IP from which you call the API. Each one must be a single IPv4 or IPv6 address; IP ranges are not supported.
- Back office login IPs: the source IPs from which you log in to the merchant back office, in the same format. This is a separate whitelist from the API one.
- Obtain your API credential and back office account: ST Pay delivers your
api_identity(API identity) and API secret key. The secret key is shown only once, when the credential is created, and ST Pay does not show it again afterwards. Store it securely right away. ST Pay also creates your merchant supervisor account for the back office and delivers its initial password, which must be changed at first login. - Complete the integration in the test environment: Implement the four APIs and the Callback as described in this document, and verify every item on the Go-live checklist.
- Go live in the production environment: The production environment's domain, credentials, and IP whitelist are completely separate from those of the test environment and must be requested separately.
The API and back office login IP whitelists and the credentials are configured by ST Pay. If you need to change any of them, contact your ST Pay integration contact. IP whitelist changes take effect in about 1 minute.
You do not need to give ST Pay a Callback URL. Send it as callback_url each time you create an order; see Callback URL for the rules.
Environments
| Environment | API domain | Merchant back office | Notes |
|---|---|---|---|
| Test environment | Provided by your ST Pay integration contact | Provided by your ST Pay integration contact | No real money is moved; use credentials issued for the test environment |
| Production environment | Provided after you complete the integration in the test environment | Provided after you complete the integration in the test environment | Real money is moved; use credentials issued for the production environment |
The full URL is "domain + path", for example https://merchant.vincoterra.com/api/v1/collect/orders. The merchant back office shares the same domain as the API (a different path), while the payment page is served from pay.vincoterra.com. All examples in this document use the production domains: merchant.vincoterra.com for the API and the merchant back office, pay.vincoterra.com for the payment page. Test-environment domains are provided separately by your ST Pay integration contact.