Skip to main content

Payout

Zoqq Payouts enables businesses to make faster, more cost-effective payouts across the globe by connecting to local clearing systems in over countries. With a single Zoqq account and/or one integration, you (and your customers) will be able to move funds globally via Zoqq’s payout network, which currently supports local and SWIFT payouts in countries/regions and over currencies.

Create Beneficiary​

This endpoint is used to create a new beneficiary account, which is required for making transfers to that recipient. To ensure the request is properly formatted, the request body must follow the specific structure (schema) provided by the Get Beneficiary Schema endpoint. This ensures that all necessary details are included and correctly formatted for successful account creation.

POST {{baseUrl}}/zoqq/api/v1/transfer/beneficiary

Description

This endpoint is used to create a new beneficiary account, which is essential for initiating transfers to that beneficiary. A beneficiary account typically includes important details such as the recipient’s name, account , and other relevant data required to process a transfer. To successfully create a beneficiary account, the request body must adhere to a specific format or structure. This structure, also known as the schema, can be retrieved using the Get Beneficiary Schema endpoint. It outlines all the required fields, data types, and any conditional logic or rules that must be followed. Using the correct schema ensures the data is valid and reduces the chances of errors during account creation or future transfers.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
AuthorizationstringYesBearer token
Content-TypestringYesMust be application/json

Request Body Parameters

ParameterTypeRequiredDescription
beneficiary_account_currencystringYesCurrency code of the beneficiary
beneficiary_account_numberstringYesAccount number of the beneficiary

Example Request Body:

{
  "beneficiary": {
    "address": {
      "city": "kol",
      "country_code": "US",
      "postcode": "4545151",
      "state": "wbg",
      "street_address": "abcde"
    },
    "bank_details": {
      "account_currency": "USD",
      "account_name": "Testairapi",
      "account_number": "4454545",
      "bank_country_code": "US",
      "bank_name": "HSBC",
      "swift_code": "{{swift-code}}"
    },
    "company_name": "Stylopay",
    "entity_type": "COMPANY"
  },
  "transfer_methods": [
    "SWIFT"
  ]
}

Request Example

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiary' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Authorization: Bearer {{AccessToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiary": {
    "address": {
      "city": "kol",
      "country_code": "US",
      "postcode": "4545151",
      "state": "wbg",
      "street_address": "abcde"
    },
    "bank_details": {
      "account_currency": "USD",
      "account_name": "Testairapi",
      "account_number": "4454545",
      "bank_country_code": "US",
      "bank_name": "HSBC",
      "swift_code": "{{swift-code}}"
    },
    "company_name": "Stylopay",
    "entity_type": "COMPANY"
  },
  "transfer_methods": [
    "SWIFT"
  ]
}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Beneficiary Created Successfully",
  "data": [
    {
      "id": "beneficiary-id",
      "beneficiary_account_currency": null,
      "beneficiary_account_number": null
    }
  ]
}

Get Beneficiary Schema​

This API retrieves the beneficiary schema required for initiating a transfer based on the specified transfer method, entity type, bank country, and account currency. This schema outlines the required fields and validations necessary for creating or validating a beneficiary profile in compliance with Zoqq's transfer policies.

This endpoint is useful when dynamically building forms or validating input fields for adding a new beneficiary during a fund transfer process.

GET {{baseUrl}}/zoqq/api/v1/transfer/beneficiaryschema

Description

Ideal for generating forms or validating beneficiary details when adding a new beneficiary in a payout.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Query Parameters

ParameterTypeRequiredDescription
beneficiary account_currencystringYesCurrency code of the beneficiary
beneficiary bank_country_codestringYesCountry code of the beneficiary
beneficiary entity_typestringYesEntity type of the beneficiary
transfer_methodstringYes"LOCAL" or "SWIFT"

Request Example

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiaryschema?account_currency=USD&bank_country_code=US&entity_type=COMPANY&transfer_method=SWIFT' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "BeneficiarySchema fetched Successfully",
  "data": [
    {
      "key": "entity_type",
      "path": "beneficiary.entity_type",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "COMPANY|PERSONAL"
      }
    },
    {
      "key": "bank_country_code",
      "path": "beneficiary.bank_details.bank_country_code",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "AD|AE|AG|AI|AL|AM|AO|AR|AS|AT|AU|AW|AZ|BA|BB|BD|BE|BF|BG|BH|BJ|BL|BM|BN|BO|BR|BS|BT|BW|BZ|CA|CF|CG|CH|CI|CK|CL|CM|CN|CO|CR|CV|CW|CY|CZ|DE|DJ|DK|DM|DO|DZ|EC|EE|EG|ES|ET|FI|FJ|FK|FM|FO|FR|GA|GB|GD|GE|GF|GG|GH|GI|GL|GM|GN|GQ|GR|GT|GW|GY|HK|HN|HR|HU|IC|ID|IE|IL|IM|IN|IS|IT|JE|JM|JO|JP|KE|KG|KH|KI|KN|KR|KW|KY|KZ|LA|LB|LC|LI|LK|LR|LS|LT|LU|LV|MA|MC|MD|ME|MF|MG|MH|MK|MN|MO|MP|MQ|MR|MS|MT|MU|MV|MW|MX|MY|NA|NC|NE|NG|NI|NL|NO|NP|NZ|OM|PA|PE|PF|PG|PH|PK|PL|PM|PR|PS|PT|PW|PY|QA|RE|RO|RS|RW|SA|SB|SC|SE|SG|SH|SI|SK|SL|SM|SN|SR|ST|SV|SZ|TC|TD|TF|TG|TH|TJ|TL|TN|TO|TR|TT|TV|TW|TZ|UA|UG|US|UY|UZ|VA|VC|VG|VN|VU|WF|WS|XK|YT|ZA|ZM|ZW"
      }
    },
    {
      "key": "account_currency",
      "path": "beneficiary.bank_details.account_currency",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "AED|AOA|ARS|AUD|BDT|BGN|BHD|BOB|BRL|BWP|CAD|CHF|CLP|CNY|COP|CZK|DKK|EGP|EUR|GBP|GMD|HKD|HUF|IDR|ILS|INR|JPY|KES|KRW|LKR|LSL|MAD|MGA|MWK|MXN|MYR|NAD|NGN|NOK|NPR|NZD|PEN|PHP|PKR|PLN|PYG|RON|RWF|SAR|SEK|SGD|THB|TRY|USD|UYU|VND|XAF|XOF|ZAR|ZMW"
      }
    },
    {
      "key": "transfer_method",
      "path": "transfer_method",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "LOCAL|SWIFT"
      }
    },
    {
      "key": "company_name",
      "path": "beneficiary.company_name",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "^[\\s\\S]{1,100}$"
      }
    },
    {
      "key": "swift_code",
      "path": "beneficiary.bank_details.swift_code",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "^[A-Z]{4}US[A-Z0-9]{2}([A-Z0-9]{3})?$"
      }
    },
    {
      "key": "account_number",
      "path": "beneficiary.bank_details.account_number",
      "required": true,
      "rule": {
        "pattern": "^[0-9A-Za-z]{1,26}$",
        "type": "string"
      }
    },
    {
      "key": "account_name",
      "path": "beneficiary.bank_details.account_name",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "^[\\s\\S]{2,200}$"
      }
    },
    {
      "key": "country_code",
      "path": "beneficiary.address.country_code",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "AD|AE|AF|AG|AI|AL|AM|AN|AO|AQ|AR|AS|AT|AU|AW|AX|AZ|BA|BB|BD|BE|BF|BG|BH|BI|BJ|BL|BM|BN|BO|BQ|BR|BS|BT|BV|BW|BZ|CA|CC|CD|CF|CG|CH|CI|CK|CL|CM|CN|CO|CR|CV|CW|CX|CY|CZ|DE|DJ|DK|DM|DO|DZ|EC|EE|EG|EH|ER|ES|ET|FI|FJ|FK|FM|FO|FR|GA|GB|GD|GE|GF|GG|GH|GI|GL|GM|GN|GP|GQ|GR|GS|GT|GU|GW|GY|HK|HM|HN|HR|HT|HU|IC|ID|IE|IL|IM|IN|IO|IQ|IS|IT|JE|JM|JO|JP|KE|KG|KH|KI|KM|KN|KR|KW|KY|KZ|LA|LB|LC|LI|LK|LR|LS|LT|LU|LV|MA|MC|MD|ME|MF|MG|MH|MK|ML|MN|MO|MP|MQ|MR|MS|MT|MU|MV|MW|MX|MY|MZ|NA|NC|NE|NF|NG|NI|NL|NO|NP|NR|NU|NZ|OM|PA|PE|PF|PG|PH|PK|PL|PM|PN|PR|PS|PT|PW|PY|QA|RE|RO|RS|RW|SA|SB|SC|SD|SE|SG|SH|SI|SJ|SK|SL|SM|SN|SO|SR|SS|ST|SV|SX|SZ|TC|TD|TF|TG|TH|TJ|TK|TL|TM|TN|TO|TR|TT|TV|TW|TZ|UA|UG|UM|US|UY|UZ|VA|VC|VE|VG|VI|VN|VU|WF|WS|XK|YE|YT|ZA|ZM|ZW"
      }
    },
    {
      "key": "postcode",
      "path": "beneficiary.address.postcode",
      "required": true,
      "rule": {
        "pattern": "^[0-9]{5}(?:-[0-9]{4})?$",
        "type": "string"
      }
    },
    {
      "key": "street_address",
      "path": "beneficiary.address.street_address",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "(^(?!\\d+$))^[\\s\\S]{5,200}$"
      }
    },
    {
      "key": "city",
      "path": "beneficiary.address.city",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "^[\\s\\S]{1,50}$"
      }
    },
    {
      "key": "state",
      "path": "beneficiary.address.state",
      "required": true,
      "rule": {
        "type": "string",
        "pattern": "US-AK|US-AL|US-AR|US-AS|US-AZ|US-CA|US-CO|US-CT|US-DC|US-DE|US-FL|US-GA|US-GU|US-HI|US-IA|US-ID|US-IL|US-IN|US-KS|US-KY|US-LA|US-MA|US-MD|US-ME|US-MI|US-MN|US-MO|US-MP|US-MS|US-MT|US-NC|US-ND|US-NE|US-NH|US-NJ|US-NM|US-NV|US-NY|US-OH|US-OK|US-OR|US-PA|US-PR|US-RI|US-SC|US-SD|US-TN|US-TX|US-UM|US-UT|US-VA|US-VI|US-VT|US-WA|US-WI|US-WV|US-WY"
      }
    },
    {
      "key": "nickname",
      "path": "nickname",
      "required": false
    },
    {
      "key": "personal_email",
      "path": "beneficiary.additional_info.personal_email",
      "required": false,
      "rule": {
        "type": "string",
        "pattern": "^(\\S+@\\S+)$"
      }
    }
  ]
}

Update Beneficiary​

This API lets you update specific fields of an existing beneficiary account, such as name, bank details without recreating the entire account. You need to provide the beneficiary ID and only the fields you want to change. The API validates the updates based on the rules for the relevant transfer corridor, ensuring data accuracy while keeping the rest of the beneficiary information unchanged.

PATCH {{baseUrl}}/zoqq/api/v1/transfer/beneficiary/{{BeneficiaryID}}

Description

This endpoint allows partial updates to an existing beneficiary's information. You only need to include the fields you want to change, such as name, bank details, or address. The updates are validated using the same schema as beneficiary creation, ensuring they meet the requirements for the relevant transfer corridor. Unspecified fields remain unchanged.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
AuthorizationstringYesBearer token
Content-TypestringYesMust be application/json

Example Request Body

Include only the fields that need updating, following the same schema as beneficiary creation:

{
  "nickname": "Air",
  "transfer_methods": ["SWIFT","LOCAL"],
  "beneficiary": {
    "entity_type": "COMPANY",
    "company_name": "WinterFell",
    "bank_details": {
      "bank_country_code": "US",
      "account_currency": "USD",
      "account_number": "12345",
      "account_name": "Test Air",
      "account_routing_value1": "021000322",
      "account_routing_type1": "aba",
      "swift_code": "{{swift-code}}"
    },
    "address": {
      "country_code": "US",
      "postcode": "10001",
      "street_address": "123 Market Street",
      "city": "New York",
      "state": "US-NY"
    },
    "additional_info": {
      "personal_email": ""
    }
  }
}

Request Example

curl --location --request PATCH \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiary/{{BeneficiaryID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "nickname": "Air",
  "transfer_methods": ["SWIFT","LOCAL"],
  "beneficiary": {
    "entity_type": "COMPANY",
    "company_name": "WinterFell",
    "bank_details": {
      "bank_country_code": "US",
      "account_currency": "USD",
      "account_number": "12345",
      "account_name": "Test Air",
      "account_routing_value1": "021000322",
      "account_routing_type1": "aba",
      "swift_code": "{{swift-code}}"
    },
    "address": {
      "country_code": "US",
      "postcode": "10001",
      "street_address": "123 Market Street",
      "city": "New York",
      "state": "US-NY"
    },
    "additional_info": {
      "personal_email": ""
    }
  }
}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Beneficiary Details Updated Successfully",
  "data": [
    {
      "id": "beneficiary-id",
      "beneficiary_account_currency": null,
      "beneficiary_account_number": null
    }
  ]
}

Get Beneficiary List​

This API retrieves a list of all beneficiaries associated with the authenticated user.

GET {{baseUrl}}/zoqq/api/v1/transfer/beneficiarylist

Description

This endpoint returns a paginated list of beneficiaries created by the user, along with their status and supported payout methods. You can filter results by status or currency and control pagination using limit and offset query parameters.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
AuthorizationstringYesBearer token
Content-TypestringYesMust be application/json

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoNumber of results per page (default: 20, max: 100)
offsetintegerNoPagination offset (default: 0)
statusstringNoFilter by beneficiary status
currencystringNoFilter by beneficiary currency

Request Example

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiarylist' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Beneficiary fetched Successfully",
  "data": [
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "USD",
        "account_name": "Air",
        "account_number": "12345",
        "bank_country_code": "US",
        "bank_name": "U.S. BANK N.A.",
        "swift_code": "swift-code",
        "local_clearing_system": null,
        "account_routing_type1": "aba",
        "account_routing_value1": "021000322",
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    },
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "USD",
        "account_name": "Schneider - Powlowski",
        "account_number": "12345",
        "bank_country_code": "US",
        "bank_name": "JPMORGAN CHASE BANK, N.A.",
        "swift_code": "swift-code",
        "local_clearing_system": null,
        "account_routing_type1": null,
        "account_routing_value1": null,
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    },
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "SGD",
        "account_name": "John Connor",
        "account_number": "12345",
        "bank_country_code": "SG",
        "bank_name": "DBS Bank/POSB",
        "swift_code": "swift-code",
        "local_clearing_system": "FAST",
        "account_routing_type1": "swift_code",
        "account_routing_value1": null,
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    },
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "USD",
        "account_name": "Sayan-usd",
        "account_number": "12345",
        "bank_country_code": "US",
        "bank_name": "Community Federal Savings Bank",
        "swift_code": null,
        "local_clearing_system": "FEDWIRE",
        "account_routing_type1": "aba",
        "account_routing_value1": "026073008",
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    },
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "USD",
        "account_name": "Sayan Koner USD ",
        "account_number": "12345",
        "bank_country_code": "US",
        "bank_name": "COMMUNITY FEDERAL SAVINGS BANK",
        "swift_code": "swift-code",
        "local_clearing_system": null,
        "account_routing_type1": null,
        "account_routing_value1": null,
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    },
    {
      "beneficiaryId": "beneficiary-id",
      "fullName": "",
      "nickname": "COMPANY",
      "bankDetails": {
        "account_currency": "SGD",
        "account_name": "sdfgh",
        "account_number": "12345",
        "bank_country_code": "SG",
        "bank_name": "ANZ Bank",
        "swift_code": "swift-code",
        "local_clearing_system": "FAST",
        "account_routing_type1": "swift_code",
        "account_routing_value1": null,
        "account_routing_type2": null,
        "account_routing_value2": null,
        "bank_branch": null
      }
    }
  ]
}

Get Beneficiary By ID​

This API retrieves detailed information about a specific beneficiary.

GET {{baseUrl}}/zoqq/api/v1/transfer/beneficiarylist/{{BeneficiaryID}}

Description

This endpoint retrieves full details of a specific beneficiary, including their account info, verification status, and supported payout methods. You must provide the beneficiary ID and required headers for authentication and identification.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Query Parameters

ParameterTypeRequiredDescription
beneficiary_idstringYesThe ID of the beneficiary to retrieve

Request Example

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiarylist/{{BeneficiaryID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Beneficiary fetched Successfully",
  "data": [
    {
      "beneficiary": {
        "additional_info": {
            "personal_email": ""
        },
        "address": {
          "city": "New York",
          "country_code": "US",
          "postcode": "10001",
          "state": "US-NY",
          "street_address": "123 Market Street"
        },
        "bank_details": {
          "account_currency": "USD",
          "account_name": "Test Air",
          "account_number": "1234567890",
          "account_routing_type1": "aba",
          "account_routing_value1": "021000322",
          "bank_country_code": "US",
          "bank_name": "U.S. BANK N.A.",
          "swift_code": "swift-code"
        },
        "entity_type": "COMPANY"
      },
      "id": "beneficiary-id",
      "nickname": "Test Air",
      "payer_entity_type": "COMPANY",
      "transfer_methods": [
        "SWIFT",
        "LOCAL"
      ]
    }
  ]
}

Delete Beneficiary​

This API removes a saved beneficiary from your payout list.

DELETE {{baseUrl}}/zoqq/api/v1/transfer/beneficiary/{{BeneficiaryID}}

Description

This endpoint deletes an existing beneficiary using the BeneficiaryID. It is typically used when a user no longer wants a beneficiary saved for future payouts.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Request Example

curl --location --request DELETE \
--url '{{baseUrl}}/zoqq/api/v1/transfer/beneficiary/{{BeneficiaryID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Beneficiary Deleted Successfully",
  "data": null
}

Create Payout​

Programmatically make cost-effective, fast and secure payouts across the globe.

POST {{baseUrl}}/zoqq/api/v1/transfer/payout

Description

This endpoint initiates a payout transfer to a registered beneficiary account. To use it, you must include the required headers for authentication, program identification, and idempotency. The request body must be in JSON format and include key details such as the beneficiary_id, transfer amount, currency, and a client reference. Optional notes can also be included. The endpoint validates the input and processes the transfer based on the provided details.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key (prevents duplicate transfers)
x-user-idstringYesUser identification key
AuthorizationstringYesBearer token
Content-TypestringYesMust be application/json

Request Body Parameters

ParameterTypeRequiredDescription
beneficiaryIdstringYesUnique identifier of the beneficiary to whom the payout is being made
destinationAmountnumberConditionalAmount to be received by the beneficiary (must be null if sourceAmount is provided)
destinationCurrencycodestringYesISO 3-letter currency code of the beneficiary’s currency (e.g., USD)
feeTypestringYesFee type for the transfer
quoteIdstringYesQuote ID associated with the transfer, provided by Zoqq during quote stage
referencestringYesPayment reference or remark
scheduledPayoutDatestringYesScheduled payout date in YYYY-MM-DD format
sourceAmountnumberConditionalAmount to be debited from the sender’s account (must be null if destinationAmount is provided)
sourceCurrencycodestringYesISO 3-letter currency code of the sender’s account (e.g., SGD)
sourceOfFundsstringYesPurpose or source of funds (e.g., salary, goods_purchased, etc.)
transferMethodstringYesTransfer method (Either SWIFT, LOCAL)
destinationCountrystringYesISO 2-letter country code of the beneficiary’s country (e.g., SG)

Example Request Body:

{
  "beneficiaryId": "{{BeneficiaryID}}",
  "destinationAmount": null,
  "destinationCurrencycode": "SGD",
  "transferMethod": "LOCAL",
  "sourceOfFunds": "professional_business_services",
  "reference": "Test reference-id",
  "sourceAmount": 10,
  "sourceCurrencycode": "USD",
  "destinationCountry": "SG",
  "feeType": "SHA",
  "quoteId":"{{QuoteID}}",
  "scheduledPayoutDate":"2025-09-04"
}

Request Examples

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/transfer/payout' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "beneficiaryId": "{{BeneficiaryID}}",
  "destinationAmount": null,
  "destinationCurrencycode": "SGD",
  "transferMethod": "LOCAL",
  "sourceOfFunds": "professional_business_services",
  "reference": "Test reference-id",
  "sourceAmount": 10,
  "sourceCurrencycode": "USD",
  "destinationCountry": "SG",
  "feeType": "SHA",
  "quoteId":"{{QuoteID}}",
  "scheduledPayoutDate":"2025-09-04"
}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Payout Created Successfully",
  "data": [
    {
      "id": "pyt_12345",
      "systemReferenceNumber": "sys_ref_67890"
    }
  ]
}

Get Payout Status​

This API retrieves the current status and details of a specific payout transaction using its payout ID.

GET {{baseUrl}}/zoqq/api/v1/transfer/payout/{{PayoutID}}

Description

This endpoint provides detailed information and the current status of a payout transaction identified by its PayoutID. The response includes transaction status, amount, beneficiary details, timestamps, and system reference data.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Request Example

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/transfer/payout/{{PayoutID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Payout Details Fetched",
  "data": [
    {
      "id": "pyt_12345",
      "status": "PROCESSING"
    }
  ]
}

Cancel Payout​

This API allows cancellation of pending payout transactions.

PATCH {{baseUrl}}/zoqq/api/v1/transfer/cancelpayout

Description

This endpoint cancels a pending payout transaction using either the payout ID or system reference number. Required headers ensure authentication and request tracking. The request body must include one of the two identifiers to locate and cancel the transaction. Only pending payouts can be canceled.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Request Body Parameters

ParameterTypeRequiredDescription
idstringConditional*Payout transaction ID
systemReferenceNumberstringConditional*System reference number

*Note: At least one of these fields must be provided

Request Example

curl --location --request PATCH \
--url '{{baseUrl}}/zoqq/api/v1/transfer/cancelpayout' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "id": "pyt_12345",
  "systemReferenceNumber": "sys_ref_67890"
}'

Response Example

{
  "code": 200,
  "status": "success",
  "message": "Payout cancelled successfully",
  "data": {}
}

Scheduled Payout List​

This API retrieves all upcoming payout transactions that are scheduled but not yet processed.

GET {{baseUrl}}/zoqq/api/v1/transfer/upcomingpayouts

Description

This endpoint returns a list of all upcoming or scheduled payout transactions for a given user or account. It can be used to track payouts that are planned but not yet completed.

Request Headers

ParameterTypeRequiredDescription
x-api-keystringYesShared X-API key provided by Zoqq
x-product-idstringYesShared ProductID By Zoqq
x-request-idstringYesIdempotency key
x-user-idstringYesUser identification key
Content-TypestringYesMust be application/json
AuthorizationstringYesBearer token

Request Example

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/transfer/upcomingpayouts' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
  "code": 404,
  "status": "error",
  "message": "No upcoming payouts found",
  "data": []
}