Skip to content

SwiftX payment API (2.5.1)

Intro

Swiftx API facilitate fast payments via bank tranfers to specified beneficiaries.

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.

    company-test-sIEUpUP7b41n51WY

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:

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "someuser-demo-1234567890ABCDEF"
}

JWT token body MUST include the following claims:

{
    "sub": "someuser-demo-1234567890ABCD", /* (your `ACCESS KEY`), the same as `kid` */
    "exp": 1234,  /* (expiration time, UNIX timestamp, UTC) */
    "iat": 1234,  /* (issued at time, UNIX timestamp, UTC) */
    "aud": "https://api.example.net",  /* (API URL, e.g. "https://api.swiftxappdev.net") */
    "iss": "https://api.example.com"   /* (API URL, e.g. "https://api.swiftxappdev.net") */
}

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

{
    "hmac": "str (SHA256 HMAC of the raw POST body)"
}

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.

Status CategoryStatusDescriptionNotes
In ProgressqueuedPayment order acceptedOrder is accepted and waiting to be submitted for processing
In ProgresspendingPayment order pendingDEPRECATED (see processing)
In ProgressprocessingPayment order is processingPayment submitted and accepted by processor
SuccesssucceededPayment executed successfully
FailedfailedPayment failedPayment failed by the processor
FailedrejectedPayment rejectedPayment rejected by processor or by API during processing (e.g API could not route)
FailedcanceledPayment is canceledDEPRECATED (see reversed)
FailedreversedPayment is reversedPayment reversed (and refunded) on the processor side
Call SupportunknownPayment state is unknownPayment has encountered uknown status by the processor, needs manual intervantion

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.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://docs.swiftxpay.com/_mock/openapi/
Swiftx Test server
https://api.swiftxapptest.net/
Swiftx Production server
https://api.swiftxapp.net/

Swiftx/v2/debug

Operations

Swiftx/v2/payment

Operations

Swiftx/v2/balance

Operations

Balance Info

Request

Get balance info

Query
countrystring(ApiCountry)required

Destination country

Enum"BGD""IND""PAK""PHL""NPL"
Headers
authorizationAuthorization (string) or Authorization (null)(Authorization)

Bearer token (JWT signed with your SECRET_KEY)

Any of:

Bearer token (JWT signed with your SECRET_KEY)

string(Authorization)
curl -i -X GET \
  'https://docs.swiftxpay.com/_mock/openapi/v2/balance?country=BGD' \
  -H 'authorization: string'

Responses

Successful Response

Bodyapplication/json
currencystring(Currency)required
balancenumber(Balance)required
wallet_currencystring(Wallet Currency)
Default "USDT"
wallet_currency_ratenumber(Wallet Currency Rate)
Default 0
wallet_balancenumber(Wallet Balance)
Default 0
Response
application/json
{
  "currency": "string",
  "balance": 0,
  "wallet_currency": "USDT",
  "wallet_currency_rate": 0,
  "wallet_balance": 0
}

Swiftx/v2/validate

Operations

Swiftx/v2/events

Operations