# SwiftX payment API


### 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`:

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

JWT token body MUST include the following claims:

```json
{
    "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:

```json
{
    "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](https://jwt.io/beta) (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 Category  | Status       | Description                   | Notes                                                                               |
|------------------|--------------|-------------------------------|-------------------------------------------------------------------------------------|
| **In Progress**  | `queued`     | Payment order accepted        | Order is accepted and waiting to be submitted for processing                        |
| **In Progress**  | `pending`    | Payment order pending         | DEPRECATED (see `processing`)                                                       |
| **In Progress**  | `processing` | Payment order is processing   | Payment submitted and accepted by processor                                         |
| **Success**      | `succeeded`  | Payment executed successfully |                                                                                     |
| **Failed**       | `failed`     | Payment failed                | Payment failed by the processor                                                     |
| **Failed**       | `rejected`   | Payment rejected              | Payment rejected by processor or by API during processing (e.g API could not route) |
| **Failed**       | `canceled`   | Payment is canceled           | DEPRECATED (see `reversed`)                                                         |
| **Failed**       | `reversed`   | Payment is reversed           | Payment reversed (and refunded) on the processor side                               |
| **Call Support** | `unknown`    | Payment state is unknown      | Payment 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.

    


### Intro

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

Version: 2.5.1

## Servers

Swiftx Test server
```
https://api.swiftxapptest.net
```

Swiftx Production server
```
https://api.swiftxapp.net
```

## Download OpenAPI description

[SwiftX payment API](https://docs.swiftxpay.com/_bundle/openapi.yaml)

## Swiftx/v2/debug

### Debug Get

 - [GET /v2/debug](https://docs.swiftxpay.com/openapi/swiftxv2debug/debug_get_v2_debug_get.md): Test endpoint to check request headers. Headers are returned in JSON body

## Swiftx/v2/payment

### Payment

 - [POST /v2/payment](https://docs.swiftxpay.com/openapi/swiftxv2payment/payment_v2_payment_post.md): Execute payment to beneficiary with specified bank details.

### Quote

 - [POST /v2/quote](https://docs.swiftxpay.com/openapi/swiftxv2payment/quote_v2_quote_post.md): Create quote for use with payment

### Quote Get

 - [GET /v2/quote/{id}](https://docs.swiftxpay.com/openapi/swiftxv2payment/quote_get_v2_quote__id__get.md): Get info about previously created Quote

### Payment Status

 - [GET /v2/payments/{id}](https://docs.swiftxpay.com/openapi/swiftxv2payment/payment_status_v2_payments__id__get.md): Get info about previously executed payment

### Payment History

 - [GET /v2/payments](https://docs.swiftxpay.com/openapi/swiftxv2payment/payment_history_v2_payments_get.md): List payments

## Swiftx/v2/balance

### Balance Info

 - [GET /v2/balance](https://docs.swiftxpay.com/openapi/swiftxv2balance/balance_info_v2_balance_get.md): Get balance info

## Swiftx/v2/validate

### Validate Account

 - [POST /v2/validate_account](https://docs.swiftxpay.com/openapi/swiftxv2validate/validate_account_v2_validate_account_post.md): Validate bank account

### Validate Bank

 - [POST /v2/validate_bank](https://docs.swiftxpay.com/openapi/swiftxv2validate/validate_bank_v2_validate_bank_post.md): Get info about previously created Quote

## Swiftx/v2/events

### Events

 - [GET /v2/events](https://docs.swiftxpay.com/openapi/swiftxv2events/events_v2_events_get.md): Stream payment events such as payment status or quote responses