SwiftX payment API (2.5.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Changelog

2.5.1 Amount required for quote

• Since quotes are not reusable since v2.5.0, we could now add requirement that quote also contains rate: Quote amount is in base currency (e.g. AED/BHD) and payment amount is in destination currency (e.g. INR) We now check that payment_amount = quote_amount * quote_rate

2.5.0 Extended sender details required for payments

• /v2/payment_ext endpoint is now merged with /v2/payment endpoint; You must supply details, like sender name, dob, some document id etc

• Quotes are now per single payment (i.e. no quote reuse, which was possible by accident)

• For more efficient routing you can now add amount, bank and bank account details to the quote which allows for more efficient routing of payments.

2.1.1 External ID for payments

• You can now supply external_id for the payment order and fetch the payment status using that id.

  POST /v2/payment (external_id body parameter)

  GET /v2/payments/{id}?external=true (external_id body parameter)

2.1.0 Extended quote and payment API

• You can now supply additional parameters to quote request (amount, acc and bank ID). These allows us to return best possible quote and increase payment success rate.

• There is a new /v2/payment_ext endpoint which allows adding sender info. This allows payments for more countries.

2.0.0 Initial release of the v2 API

Credentials

Before using this API you need to obtain valid credentials:

• ACCESS KEY: Random base64 encoded string with custom prefix
• SECRET KEY: Random base64 encoded string

If possible, you need to keep ACCESS_KEY private and under no circumstances you should share your SECRET KEY. For user convenience, ACCESS KEY includes custom prefix in the value, e.g.

where the first part is your company tag, followed by key usage hint and last part is a random value.

Authentication

For API authentication we use JWT/Bearer tokens, signed with your SECRET KEY

Currently supported JWT algorithms are:

• HS256

JWT token header MUST include kid:

JWT token body MUST include the following claims:

In addition to the above, you can add hmac claim for POST requests:

This allows attesting that POST payloads are not modified in transit.

Using fast expiring tokens with HMAC adds additional guards so your requests can't be intercepted/forged, nor replayed.

Swiftx doesn't provide JWT editor for the time being, you can use the excellent jwt.io (password is 'jwtv2')

Transaction states

Transactions accepted by the API can be in one of the following states. As soon as the order is accepted, you will get unique id in the response, which can base used to track the transaction.

Please note that orders rejected up-front by the API with 4xx (authentication or validation errors) are not represented in the state table, since they've never been accepted for processing.

Settlement currencies

This API enables processing and settlement of transactions in fiat currency USD, and stable coins: USDT and USDC. It supports seamless currency conversion, validation, and settlement routing between traditional and digital assets.