# Stabo Developer Docs

- Guides
  - [Overview](/en/docs/guide): Stabo public API product lines, integration steps, and documentation map.
  - [Quickstart](/en/docs/guide/quickstart): Prerequisites, environments, and your first request.
  - [Authentication](/en/docs/guide/authentication): Obtain an Access Token with the OAuth2 Client Credentials flow.
  - [Conventions](/en/docs/guide/conventions): Protocol, request headers, response format, data formats, and idempotency.
  - [Webhooks](/en/docs/guide/webhooks): Delivery mechanism, request headers, event structure, and signature verification.
  - [Best practices](/en/docs/guide/best-practices): Idempotency and retries, reconciliation and compensation, security advice, and checklists for integration testing and go-live.

  - **Product Guides**
  - [Checkout product guide](/en/docs/guide/checkout): Hosted checkout page, Payment Intent, Refund, Webhook events, and status reference. For endpoint details, see the API reference.
  - Business Collection
    - [Business Collection](/en/docs/guide/business-collection): Collect in local fiat currency and receive funds as stablecoins in your Stabo wallet. On-Ramp is currently available.
    - [On-Ramp](/en/docs/guide/business-collection/on-ramp): Buy USDT with Mexican pesos (MXN). Receive account opening and queries, quotes, order creation and queries, order statuses, and Webhook events. For endpoint details, see the API Reference.
  - [Payment product guide](/en/docs/guide/payment): Balance inquiry, transfers, transaction inquiry, SWIFT messages, virtual accounts, and credit notifications. See the API reference for endpoint details.
  - [Payment reference](/en/docs/guide/payment-reference): Charge bearer, purpose codes, transaction type codes, country codes, and virtual account statuses.
- API Reference
  - [Open a receive account](/en/docs/api/business-collection/on-ramp/createOnRampReceiveAccount): Open a dedicated receiving CLABE for a payer. Opening takes a few minutes. Call this endpoint when the payer registers or is linked. Do not wait until payment time to open the account.

This endpoint is idempotent. Repeated calls with the same `payerId` return the current status of the same receive account and do not open another account. `Idempotency-Key` is not required.

Opening an account does not require payer KYC. You submit KYC when you create an order.

This release does not push notifications for opening results. Use the Retrieve a receive account endpoint, and wait at least 1 minute between requests.

The receive account does not expire. All future orders for the same payer use this CLABE.
  - Business Collection
    - On Ramp: Collect local fiat and convert it to USDT. Get quotes, create and retrieve orders, and open and retrieve receive accounts.
      - [Open a receive account](/en/docs/api/business-collection/on-ramp/createOnRampReceiveAccount): Open a dedicated receiving CLABE for a payer. Opening takes a few minutes. Call this endpoint when the payer registers or is linked. Do not wait until payment time to open the account.

This endpoint is idempotent. Repeated calls with the same `payerId` return the current status of the same receive account and do not open another account. `Idempotency-Key` is not required.

Opening an account does not require payer KYC. You submit KYC when you create an order.

This release does not push notifications for opening results. Use the Retrieve a receive account endpoint, and wait at least 1 minute between requests.

The receive account does not expire. All future orders for the same payer use this CLABE.
      - [Retrieve a receive account](/en/docs/api/business-collection/on-ramp/getOnRampReceiveAccount): Retrieve the opening status and CLABE of a payer's receive account. The response structure is the same as the Open a receive account response.

You can only retrieve payers of your own merchant account. A `payerId` that has never been opened returns "receive account not found".
      - [Get a quote](/en/docs/api/business-collection/on-ramp/getOnRampQuote): Get a reference price. A quote does not lock the price. The final price is the one in the order creation response.

Quotes support MXN amounts only. You can create an order by MXN (`fiatAmount`) or USDT (`cryptoAmount`) amount.

A quote does not generate a quote ID. You do not need to pass quote information when you create an order.
      - [Create an order](/en/docs/api/business-collection/on-ramp/createOnRampOrder): Create an On-Ramp order and return payment instructions. On success, the endpoint returns HTTP 200 and the new order has `status` `AWAITING_PAYMENT`.

The payer must transfer `fiatAmount` MXN to `paymentInfo.clabe` before `expiresAt`.

The provider sets the order price in real time. It can differ from the quote. The order creation response is authoritative.

Pass exactly one of `fiatAmount` and `cryptoAmount`.

When you create an order by `fiatAmount`, the provider confirms the USDT amount to be credited. The credited amount is the `cryptoAmount` in the response. Before the provider confirms, `cryptoAmount` can be empty.

An empty `paymentInfo` means the provider has not yet confirmed the collection. Retry the order creation with the same `Idempotency-Key`, or retrieve the order later.

If the provider rejects the request, the order is set to `FAILED`. A replay with the same `Idempotency-Key` returns that `FAILED` order.

Payer KYC is only forwarded to the provider. Stabo does not store it, and does not return the ID number or contact details in responses.

The payer's receive account must already be open. See the Open a receive account endpoint. If it is not open, order creation returns "receive account being opened" and does not create an order.
      - [Retrieve an order](/en/docs/api/business-collection/on-ramp/getOnRampOrder): Retrieve an order by its Stabo order ID. The response structure is the same as the order creation response.

You can only retrieve On-Ramp orders of your own merchant account. Other orders return "order not found".

Use Webhooks as the primary channel and order queries as a fallback. If you poll, wait at least 30 seconds between requests, and stop when the order reaches a final status.

If a Webhook and an order query disagree, the order query result is authoritative.
  - Checkout
    - Payment Intent: Create a Payment Intent, retrieve payment details, and list payments with pagination.
      - [List Payment Intents](/en/docs/api/checkout/payment-intent/listPaymentIntents): Lists Payment Intents with pagination. Pass filters as query parameters.
      - [Create a Payment Intent](/en/docs/api/checkout/payment-intent/createPaymentIntent): Creates a Payment Intent and generates a hosted checkout page link. After creation succeeds, redirect the customer to `checkoutUrl` in the response to complete the payment.

Returns HTTP 200 on success. After creation, `status` is `AWAITING_PAYMENT`.
      - [Retrieve a Payment Intent](/en/docs/api/checkout/payment-intent/getPaymentIntent): Retrieves the payment details of a Payment Intent by its ID.
    - Refund: Create a refund, list refunds, and retrieve refund details.
      - [List Refunds](/en/docs/api/checkout/refund/listRefunds): Lists the refunds of the specified Payment Intent with pagination.
      - [Create a Refund](/en/docs/api/checkout/refund/createRefund): Creates a refund for the specified Payment Intent. Partial and full refunds are supported. If you omit `amount`, the remaining refundable amount is refunded. A refund first enters `PENDING_APPROVAL` and is executed after operations approves it.

Returns HTTP 200 on success.
      - [Retrieve a Refund](/en/docs/api/checkout/refund/getRefund): Retrieves refund details by Refund ID. The refund must belong to the Payment Intent in the path. Otherwise, the request is handled as "not found".
  - Payment
    - Balance: Query the available balance of an account.
      - [Query balance](/en/docs/api/payment/balance/queryBalance): Query the available balance of an account.
    - Transfer: Intra-bank transfers, MEPS+ transfers, cross-border remittances, and their result queries.
      - [Intra-bank transfer](/en/docs/api/payment/transfer/createIntraBankTransfer): Intra-bank transfer between accounts. All currencies are supported. Use it to move funds between different accounts within the same bank.

**Notes**

- `remarks` supports only alphanumeric characters, spaces, and the special characters `/ - ? : ( ) . , ' +`
- If the `PROCESSING` status is returned, wait 5 minutes and then call the result query endpoint to confirm the final status
- For orders paid out via POBO, the response returns `poboAccountNo` / `poboAccountName`. When you call the result query endpoint, we recommend passing `accountNumber=poboAccountNo` to explicitly specify the POBO payout account. If `accountNumber` is not passed, the system automatically matches the corresponding POBO payout account based on `referenceNo`.
      - [Query intra-bank transfer result](/en/docs/api/payment/transfer/queryIntraBankTransfer): Query the result status of an intra-bank transfer. If the transfer returns the `PROCESSING` status, call this endpoint to confirm the final status.
      - [MEPS+ transfer](/en/docs/api/payment/transfer/createMepsTransfer): Make a real-time local transfer in Singapore through MEPS+ (MAS Electronic Payment System).

Features:

- SGD only
- Real-time settlement
- Suitable for high-value local transfers

**Notes**

- `beneficiaryName`, `beneficiaryAddress`, and `remarks` support only alphanumeric characters, spaces, and the special characters `/ - ? : ( ) . , ' +`
- If the beneficiary bank is not a MEPS+ participant, provide the intermediary bank details
- For orders paid out via POBO, the response returns `poboAccountNo` / `poboAccountName`. When you call the result query endpoint, we recommend passing `accountNumber=poboAccountNo` to explicitly specify the POBO payout account. If `accountNumber` is not passed, the system automatically matches the corresponding POBO payout account based on `referenceNo`.
      - [Query MEPS+ transfer result](/en/docs/api/payment/transfer/queryMepsTransfer): Query the result status of a MEPS+ transfer.
      - [Cross-border remittance](/en/docs/api/payment/transfer/createSwiftTransfer): Make a cross-border remittance through the SWIFT network. **Note**: The GLDB provider does not support cross-border remittances in SGD.

**Notes (GLDB provider)**

- SGD is not supported
- If a BIC code has fewer than 11 characters, pad it with `X`
- `beneficiaryName`, `beneficiaryAddress`, and `remarks` support only alphanumeric characters, spaces, and the special characters `/ - ? : ( ) . , ' +`
- For orders paid out via POBO, the response returns `poboAccountNo` / `poboAccountName`. When you call the result query endpoint, we recommend passing `accountNumber=poboAccountNo` to explicitly specify the POBO payout account. If `accountNumber` is not passed, the system automatically matches the corresponding POBO payout account based on `referenceNo`.
      - [Query cross-border remittance result](/en/docs/api/payment/transfer/querySwiftTransfer): Query the result status of a cross-border remittance.
    - Transaction: Transaction history queries and MT/MX message queries.
      - [Query transaction history](/en/docs/api/payment/transaction/queryTransactionHistory): Query the transaction history of an account, with pagination. Use it for reconciliation and financial reporting.
      - [Query MT/MX message](/en/docs/api/payment/transaction/queryMtMxMessage): Query the raw MT/MX SWIFT message associated with a transfer. Use it for compliance audits and troubleshooting.

For examples of `messageContent` in each scenario, see the [Payment product guide](/en/docs/guide/payment).
    - Fee: Query the estimated fee for a transfer.
      - [Query estimated transfer fee](/en/docs/api/payment/fee/estimateFee): Calculate the estimated fee based on the transfer type and amount.
    - Virtual Account: Apply for, update, and query virtual account applications, and query virtual accounts.
      - [List virtual accounts](/en/docs/api/payment/virtual-account/listVirtualAccounts): Query all opened virtual accounts of the MSO, with pagination.
      - [Apply for a virtual account](/en/docs/api/payment/virtual-account/openVirtualAccount): Apply for a virtual sub-account for an MSO (Money Service Operator) customer. Use it when a payment institution opens a dedicated virtual account for each of its downstream merchants.

**Notes**

- After submission, the application requires bank review. Track the application status with the query endpoints
- After the application succeeds, the virtual account number is returned in the application details
      - [Retrieve a virtual account](/en/docs/api/payment/virtual-account/getVirtualAccount): Query the details of a virtual account by its virtual account number. The response fields are the same as the elements of the `records` array in List virtual accounts.
      - [List virtual account applications](/en/docs/api/payment/virtual-account/listVirtualAccountRequests): Query all virtual account applications of the MSO, with pagination.
      - [Retrieve a virtual account application](/en/docs/api/payment/virtual-account/getVirtualAccountRequest): Query the details of a virtual account application by its application number.
      - [Update a virtual account application](/en/docs/api/payment/virtual-account/updateVirtualAccountRequest): Update the parameters of a virtual account application in PENDING status. Only unprocessed applications can be updated.

**Notes**

- You can update only applications in PENDING status
- Newly uploaded files overwrite the existing files
- For files, the latest submission prevails. Resubmit all files with every submission
- Help
  - [Error codes](/en/docs/help/errors): The error response format, how HTTP status codes map to the code in the response body, and how to handle each error.
  - [FAQ](/en/docs/help/faq): Common integration questions, and how to contact technical support.
  - [Changelog](/en/docs/help/changelog): Version changes of the public API documentation.