1 of 36

Payswiftly API

Overview

The Payswiftly Payout API enables businesses to manage automated financial transactions by integrating key payout processes. Here’s a more detailed guide on how to utilize the API:

Authentication: Each request requires an API key for authorization. Set this up first to gain access to all API endpoints.
Create Receivers: Begin by using the POST /receivers endpoint to create a new receiver profile. This requires the receiver's personal details, such as name, email, and phone number.
Add Bank Accounts: After creating a receiver, associate a bank account with them using the POST /bank-accounts endpoint. You'll need the bank details like the account number and branch information.
Initiate Payouts: Once the receiver and their bank account are set up, initiate a payout using the POST /payouts endpoint. Specify the receiver's ID and the amount to transfer.
Track Transactions: To monitor the status of payouts, you can use the GET /payouts/{payout_id} endpoint to check if the payout was successful, pending, or failed.
Webhooks: To handle event-driven updates, such as successful payouts or errors, register webhooks with the API. Webhooks will notify your system when an event occurs, enabling real-time tracking.
Error Handling: Every API response includes status codes. The documentation lists possible errors, like invalid parameters or authentication failures, and provides guidance on troubleshooting.

Example Workflow:

Authenticate using your API key.
Create a receiver with their details.
Attach a bank account to the receiver.
Execute the payout.
Monitor the payout status.
Use webhooks for real-time event notifications.

Error Codes

Receiver

Receiver Account

Payout

Payout API

Receiver

Create New Receiver

Create a new receiver under a SubAccount for receiving the payout.

Create a New Receiver

POST /api/receiver

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

subaccount_id*

string

Subaccount ID of the receiver user.

first_name*

string

First Name of the receiver user.

last_name*

string

Last Name of the receiver the user.

middle_name

string

Middle Name of the receiver the user.

email*

string

Email of the receiver the user.

dob*

string

Date of Birth of the receiver the user. In the format of YYYY-MM-DD

dialcode*

string

Country Dial Code of the receiver the user. (for example, 61, 353 , and so on)

phone*

string

Phone of the receiver the user.

address*

string

Address of the receiver the user.

address2

string

Additional information related to the street.

gender

string

Gender of the receiver the user.

city*

string

City, town, or another settlement.

state*

string

State, region, district, county or another territorial entity inside a country.

postcode*

string

Address postal code.

country*

string

Alpha-3 country code (for example, DEU, GBR, ARG, and so on).

reference

string

Your reference for the receiver. This is usually a unique ID in your system.

* is mandatory parameter

Example body request

{
    "subaccount_id": "3dc81811-8cdb-49c6-8f9e-9b25ea4544b7"
    "first_name": "David",
    "last_name": "Lahm",
    "middle_name": "Robert",
    "email":"davidrlahm84@gmail.com",
    "dob": "1990-03-21",
    "dialcode": "61",
    "phone": "213094857",
    "address": "122 Grenfell St",
    "gender": "M",
    "city": "Adelaide",
    "state": "SA",
    "postcode": "5000",
    "country": "AUS",
    "reference": "david8740"
}

Response

{
    "message": "Receiver created successfully",
    "payload": {
        "receiver_id": "d81b714c-a082-431a-8935-d0c67ad22c2d",
        "first_name": "David",
        "last_name": "Lahm",
        "email": "davidrlahm84@gmail.com"
    }
}

{
    "message": "There was an error while creating a receiver",
    "error": [
        {
            "code": "REVR201",
            "message": "Email already exist"
        }
    ]
}

KYC Verification for Payout

After successfully creating a new receiver using the Create New Receiver API, the system will automatically send a KYC Verification for Payments email to the email address provided in the request.

What Happens Next?

Email Notification: The receiver will receive an email containing a secure link to complete their KYC (Know Your Customer) verification.
Identity Confirmation: The receiver must click the link in the email to confirm their personal details.
Document Upload: As part of the verification process, the receiver will be required to upload the necessary identification documents.
Verification Review: Once the receiver submits their details and documents, the system will review them for compliance before Subaccount can create payout for them.

Important Notes:

• The verification link is time-sensitive and will expire after a set period.

• If the receiver does not complete the KYC verification, their account KYC status will remain pending for payouts until verification is completed.

• If the receiver does not receive the email, they should check their spam folder or request a new verification email.

Once the receiver successfully completes their KYC verification, the system will trigger a receiverKycUpdate webhook notification. This allows Subaccount to be notified in real time when a receiver is fully verified and eligible for payouts.

Add Receiver Account (v.1) ⚠️

Create a new receiver account for receiver

Create a New Receiver Account

POST /api/receiveraccount

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

bsb*

string

BSB of receiver account.

account_number*

string

Account number of receiver account.

account_type*

string

Account Type of receiver account. 'I' is Individual and 'B' is Business

* is mandatory parameter

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
    "account_type": "I", // For 'Individual'
    "bsb": "012002",
    "account_number": "111136"
}

Response


{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "bsb": "012003",
        "account_number": "712179",
        "status": "pending",
        "confirm_status": "unconfirmed"
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

Add Receiver Account (v.2)

International

Virtual Card

Create a new receiver account for receiver

International Virtual Card Payments will be available 31/03/2025. Please speak with your account manager for more information.

Create and Issue Virtual Card Receiver Account

POST /api/receiver-account/<currency>/virtual-card

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

* is mandatory parameter

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75"
}

Response

{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "status": "complete",
        "confirm_status": "confirmed",
        "card_type": "mastercard",
        "card_no": "4111111111111111",
        "cvv": "321",
        "expiry_month": "04", // MM
        "expiry_year": "2027" // YYYY
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

Australia (AUD)

Direct Entry

Create a new receiver account for receiver

Create a New Direct Entry Receiver Account

POST /api/receiver-account/aud/direct-entry

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

bsb*

string

BSB of receiver account.

account_number*

string

Account number of receiver account.

* is mandatory parameter

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
    "bsb": "012002",
    "account_number": "111136"
}

Response

{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "status": "pending",
        "confirm_status": "unconfirmed"
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

Canada (CAD)

EFT

Create a receiver account for paying an EFT CAD Payment

Create a New EFT Receiver Account

POST /api/receiver-account/cad/eft

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

routing_number*

string

Routing Number of the Receiver's bank account

account_number*

integer

Account Number of the Receiver's bank account

account_type*

string

"checking" or "savings" only

* is mandatory parameter

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
    "routing_number": "12345-001", // Format: 5-digit transit number + dash + 3-digit institution number
    "account_number": "123456789", // Typically 7–12 digits
    "account_type": "checking" // Can be either "checking" or "savings"
}

Response

{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "status": "pending",
        "confirm_status": "unconfirmed"
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

Digital Payment

Create a receiver account for paying a Digital CAD Payment

Create a New Digital Receiver Account

POST /api/receiver-account/cad/digital

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

recipient*

Email address of recipient.

name*

string

Name of recipient.

description

string

Optional description for receiver account.

* is mandatory parameter

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
    "recipient": "johndoe@email.com",
    "name": "John Doe Inc."
}

Response

{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "status": "pending",
        "confirm_status": "unconfirmed"
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

Europe (EUR)

SEPA

Create a new receiver account for receiver

Create a New Direct Entry Receiver Account

POST /api/receiver-account/eur/sepa

Headers

Body

* is mandatory parameter

Example body request

Response

New Zealand (NZD)

Direct Credit

Create a new receiver account for receiverDirect Credit

NZD Direct Credit Payments will be available 31/03/2025. Please speak with your account manager for more information.

Create a New Direct Credit Receiver Account

POST /api/receiver-account/nzd/direct-credit

Headers

Name

Value

x-api-key

<token>

signature

<token>

Body

Name

Type

Description

receiver_id*

string

Receiver ID of receiver account.

account_number*

string

In format of BBBBBB-AAAAAAA-SSS * *

* is mandatory parameter * * BBBBBB = Bank & branch code (6 digits) , AAAAAAA = Account number (7 digits), SSS = Suffix (2-3 digits)

Example body request

{
    "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
    "account_number": "123456-0789123-00"
}

Response

{
    "message": "Receiver account created successfully",
    "payload": {
        "receiver_account_id": "c7ded40b-1524-49f4-ae3f-ee974cbe6fdd",
        "receiver_id": "a2bb66db-7067-44a2-8067-1393b682bc75",
        "status": "pending",
        "confirm_status": "unconfirmed"
    }
}

{
    "message": "There was an error while creating a receiver account",
    "error": [
        {
            "code": "REAC211",
            "message": "Receiver ID is not valid"
        }
    ]
}

United States of America (USD)

ACH

Create a receiver account for paying an ACH USD Payment

USD ACH Payments will be available 31/03/2025. Please speak with your account manager for more information.

Create a New ACH Receiver Account

POST /api/receiver-account/usd/ach

Headers

Body

* is mandatory parameter

Example body request

Response

Get Receiver

Get Receiver By ID

GET /api/receiver/<id>

Get a receiver data under subaccount by ID.

Headers

Example request

Response

Get Receiver list

GET /api/receiver

Get receiver list under subaccount.

Headers

Request query parameter

* is mandatory parameter

Example query parameter request

Response

Get Receiver Bank Account

Get Receiver Account By ID

GET /api/receiver-account/<id>

Get receiver account data under subaccount by ID.

Headers

Name

Value

x-api-key

<token>

signature

<token>

Example request

/api/receiver-account/6dea4c0d-7825-4636-a0b0-c4895d451244

Response

{
    "message": "Receiver found",
    "payload": {
        "id": "6dea4c0d-7825-4636-a0b0-c4895d451244",
        "first_name": "Nademoa",
        "last_name": "Tesla",
        "email": "ex@teslastudio.com",
        "dob": "1973-12-12",
        "gender": "M",
        "aka": "",
        "occupation": "",
        "reference": "4464",
        "mobile_international_dialcode": "61",
        "mobile": "483908899",
        "home_phone_international_dialcode": "",
        "home_phone": "",
        "individual_or_business": "I",
        "abn": "",
        "nzbn": "",
        "acn": "",
        "kyc_status": "completed",
        "address_data": {
            "address": "111/22222",
            "address2": "Paklok Rd",
            "city": "Phuket",
            "state": "PK",
            "country": "THA",
            "postcode": "83110"
        },
        "bank_account_data": {
            "account_number": "111136",
            "bank_code": "ANZ",
            "bsb": "012002"
        },
        "account_data": {
            "receiver_accepted": true,
            "receiver_address_accepted": true,
            "receiver_address_outcome": null
        }
    },
}

{
    "message": "Get receiver account failed",
    "error": [
        {
            "code": "REAC104",
            "message": "Receiver ID not found"
        }
    ]
}

Get Receiver Account List From Receiver

GET /api/receiver-account/receiver/<id>

Get receiver account from receiver.

Headers

Name

Value

x-api-key

<token>

signature

<token>

Example request

/api/receiver-account/receiver/a6980641-e785-447a-960d-036bd29c5ece

Response

{
    "message": "Receiver Account found",
    "payload": [
        {
            "id": "6dea4c0d-7825-4636-a0b0-c4895d451244",
            "first_name": "Nademoa",
            "last_name": "Tesla",
            "email": "ex@teslastudio.com",
            "dob": "1973-12-12",
            "gender": "M",
            "aka": "",
            "occupation": "",
            "reference": "4464",
            "mobile_international_dialcode": "61",
            "mobile": "483908899",
            "home_phone_international_dialcode": "",
            "home_phone": "",
            "individual_or_business": "I",
            "abn": "",
            "nzbn": "",
            "acn": "",
            "kyc_status": "completed",
            "address_data": {
                "address": "111/22222",
                "address2": "Paklok Rd",
                "city": "Phuket",
                "state": "PK",
                "country": "THA",
                "postcode": "83110"
            },
            "bank_account_data": {
                "account_number": "111136",
                "bank_code": "ANZ",
                "bsb": "012002"
            },
            "account_data": {
                "receiver_accepted": true,
                "receiver_address_accepted": true,
                "receiver_address_outcome": null
            }
        },
        {
            "id": "e5b088e1-cf4a-4e91-bb65-3c7e07b9b314",
            "first_name": "Alexa",
            "last_name": "Riverstone",
            "email": "alex@riverstudio.com",
            "dob": "1984-05-23",
            "gender": "F",
            "aka": "",
            "occupation": "",
            "reference": "5589",
            "mobile_international_dialcode": "44",
            "mobile": "7700986543",
            "home_phone_international_dialcode": "",
            "home_phone": "",
            "individual_or_business": "I",
            "abn": "",
            "nzbn": "",
            "acn": "",
            "kyc_status": "completed",
            "address_data": {
                "address": "88/99999",
                "address2": "Evergreen Terrace",
                "city": "Springfield",
                "state": "SP",
                "country": "USA",
                "postcode": "49007"
            },
            "bank_account_data": {
                "account_number": "224455",
                "bank_code": "ANZ",
                "bsb": "031200"
            },
            "account_data": {
                "receiver_accepted": true,
                "receiver_address_accepted": true,
                "receiver_address_outcome": null
            }
        }
    ]
}

{
    "message": "Get receiver account failed",
    "error": [
        {
            "code": "REAC101",
            "message": "Receiver Account ID not found"
        }
    ]
}

Payout

Webhooks

Payout Notifications

Payout webhooks notify your system of important payout events, such as when a payout is successfully processed or if it fails. This allows for real-time updates, ensuring your system remains synchronized with transaction statuses.

Payout Webhook Structure Data Type: JSON

The webhook payload is delivered in JSON format, a structured data format commonly used for APIs. Each payload includes:

Payout Notification Event

Payout Notification Status

Example

Balance

Account

Webhooks

Account Notifications

Account Webhook Structure Data Type: JSON

The webhook payload is delivered in JSON format, a structured data format commonly used for APIs. Each payload includes:

Account Notification Event

Account Notification Status

Example

Batch

Get Payout

Get Payout by ID

GET /api/payout/<id>

Get Payout by ID

Headers

Name

Value

x-api-key

<token>

signature

<token>

Example request

/api/payout/3971f24a-b901-4bdb-b3a5-7690ca350cd3

Response

{
    "message": "Payout found",
    "payload": {
        "id": "3971f24a-b901-4bdb-b3a5-7690ca350cd3",
        "created_at": "1710144053053",
        "provider_reference": "dev-ref-a00020",
        "batch_id": "",
        "asset": "AUD",
        "reference": "dev-ref-a00020",
        "merchant": "MERC#9f05dc98-47bd-47f2-a039-8d9889fdfb7a",
        "fee_data": {
            "fee_value": "200",
            "feetemplate_id": "10543412-9de9-4adb-814c-60fd5ea4aba8",
            "fixed": 0,
            "feegroup_id": "4d8d52ee-47e8-425b-9677-878b127147b9",
            "percentage": 10,
            "min_amount": 20
        },
        "note": "devid a00020",
        "payout_data": {
            "status": "IN PROGRESS",
            "transaction_is_duplicated": false,
            "receiver_is_invalid": false,
            "accepted": true,
            "errors": null,
            "transaction_id": "20020105",
            "sender_is_invalid": false
        },
        "status": "successful",
        "amount": 2000,
        "subaccount": {
            "id": "ccb93d70-00d0-4ec4-a454-32bfc8e8428f"
        },
        "receiver": {
            "id": "e4908c83-6656-408a-8ba2-61dae8f039a5",
            "firstname": "Devid-A",
            "lastname": "Tesla",
            "email": "david@teslastudio.com"
        },
        "receiver_account": {
            "id": "6afec8ad-c026-463b-9f09-f60adfae10a0",
            "email": "david@teslastudio.com",
            "bsb": "012002",
            "bank_code": "ANZ",
            "account_number": "223344556677"
        },
        "payout_provider": {
            "id": "eb68d16a-d395-4acd-a8bf-d01de92f949b"
        },
        "transactions": [
            {
                "transaction_id": "6af8c51c-e8d6-4ba5-b3d7-c966b9f14fb9",
                "amount": -1800,
                "asset": "AUD",
                "status": "complete",
                "created_at": "1710144077857",
                "updated_at": "1710144379146",
                "transaction_type": "payout"
            },
            {
                "transaction_id": "4eefc21c-286e-48d9-82a8-788bfbd4175f",
                "amount": -200,
                "asset": "AUD",
                "status": "complete",
                "created_at": "1710144077857",
                "updated_at": "1710144379226",
                "transaction_type": "fee"
            }
        ]
    }
}

{
    "message": "Get payout failed",
    "error": [
        {
            "code": "PAYO101",
            "message": "Payout ID not found"
        }
    ]
}

Get Payout list

GET /api/payout/

Get Payout list

Headers

Name

Value

x-api-key

<token>

signature

<token>

Request query parameter

Name

Type

Description

subaccount_id*

string

Subaccount ID

limit

string

Limit of request data.

from

string

Filter by create date from in format 'YYYY-MM-DD hh:mm'.

to

string

Filter by create date to in format 'YYYY-MM-DD hh:mm'.

status

string

Filter by payout status.

0 = AWAITING 1 = PENDING 2 = UNASSESSED 3 = IN_PROGRESS 4 = SUCCESSFUL 5 = CANCELLED 6 = FAILED 7 = SUCCESSFUL_PENDING_KYC

2 * is mandatory parameter

Example query parameter request

/api/payout?subaccount_id=3dc81811-8cdb-49c6-8f9e-9125ea4540b0&from=2024-02-08 09:00&to=2024-03-11 06:21&limit=1

Response

{
    "message": "Payout found",
    "payload": [
        {
        "id": "ce74a54d-cd7d-475b-8213-b70a7a9c47e0",
        "created_at": "1707384569939",
        "provider_reference": "ref-22aud",
        "batch_id": "",
        "asset": "AUD",
        "reference": "ref-22aud",
        "fee_data": {
            "feetemplate_id": "10543412-9de9-4adb-814c-60fd5ea4aba8",
            "fixed": 0,
            "feegroup_id": "4d8d52ee-47e8-425b-9677-878b127147b9",
            "percentage": 10,
            "min_amount": 20
        },
        "note": "22 AUD payout",
        "payout_data": {
            "status": "PENDING",
            "transaction_is_duplicated": false,
            "receiver_is_invalid": false,
            "accepted": true,
            "errors": null,
            "transaction_id": "20019915",
            "sender_is_invalid": false
        },
        "status": "pending",
        "amount": "2200",
        "subaccount": {
            "id": "ccb93d70-00d0-4ec4-a454-32bfc8e8428f"
        },
        "receiver": {
            "id": "617fc7a4-70e2-47d3-a5b0-84a5bc17a4a0",
            "firstname": "Exel",
            "lastname": "Receiver",
            "email": "ex@teslastudio.com"
        },
        "receiver_account": {
            "id": "fdf427df-1093-4d77-84a7-b08ac67f453f",
            "email": "ex@teslastudio.com",
            "bsb": "012040",
            "bank_code": "ANZ",
            "account_number": "111111222255"
        },
        "payout_provider": {
            "id": "eb68d16a-d395-4acd-a8bf-d01de92f949b"
        }
    ],
    "lastkey": "eyJlbnRpdHkiOiJQQVlPIyIsIlBLIjoiUEFZTyM2ODNlN2UwMS0yOWI2LTQ4ZDMtOTNlZi1kODIyNzU3ZmIxOWUiLCJTSyI6IlJFVlIjMTkwNjgwZTEtZjRjNC00ZTkwLTkyOTgtODA3M2NlZWY5MmVlIiwiY3JlYXRlZF9hdCI6IjE3MTkzNjU5MTEwMzUifQ=="
}