OK WIRE DEVELOPERS

Cross-border payment APIs,integrated with your workflows.

Integrate individual payments, customer registration, collection accounts, receipt queries and account balances.

REST APIJSONServer-to-server

Request and response illustration · Selected fieldsREST / JSON

Send requestmerchant / balancePOST

https://api.example.com
/v1/merchant/fundPool/balance

{
  "currency": "USD",
  "appKey": "your_app_key",
  "sign": "…"
}

Receive responsecode: 0

availableBalance12,000 USD

All request URLs use example domains. Replace them with your assigned service URL when integrating.

api.example.com

On this page

01 / Quickstart

API integration workflow

Configure access and validate queries before integrating the required business endpoints.

01
Prepare your access
Complete merchant onboarding and obtain your appKey, appSecret and environment details.
Open the business console
02
Configure authentication
Store credentials on the server and confirm endpoint authentication, encryption mode and applicable IP settings.
Signing & authentication
03
Make your first query
Use a balance query to verify signing, connectivity and response handling.
Query account balances
04
Connect your workflow
Integrate payment or collection endpoints, retain business identifiers and handle status queries and asynchronous notifications.
Explore the API

02 / Query account balances

Query account balances

Use the read-only currency account balance endpoint to validate the request format. Run examples on your server; this website does not submit live business requests.

export OKWIRE_APP_KEY='your_app_key'
export OKWIRE_APP_SECRET='your_app_secret'
TIMESTAMP="$(date +%s)000"
NONCE="$(openssl rand -hex 12)"
SIGN=$(printf '%s' "appKey=$OKWIRE_APP_KEY&appSecret=$OKWIRE_APP_SECRET&currency=USD&nonce=$NONCE&timestamp=$TIMESTAMP" \
  | openssl dgst -md5 -r | cut -d ' ' -f 1)

curl --request POST \
  'https://api.example.com/v1/merchant/fundPool/balance' \
  --header 'Content-Type: application/json' \
  --data "{\"appKey\":\"$OKWIRE_APP_KEY\",\"currency\":\"USD\",\"timestamp\":$TIMESTAMP,\"nonce\":\"$NONCE\",\"sign\":\"$SIGN\"}"

Node.js 18+ / Python 3: first set OKWIRE_APP_KEY and OKWIRE_APP_SECRET on your server. This example signs flat fields only.

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "data": [
      {
        "fundPoolId": 1001,
        "merchantId": 2001,
        "currency": "USD",
        "balance": 12500,
        "frozenBalance": 500,
        "availableBalance": 12000,
        "status": 1,
        "channel": 0
      }
    ]
  }
}

Example response · Illustrative amounts and IDs

A code of 0 indicates business success; balances are in data.data. Handle both HTTP errors and non-zero business codes.

03 / Signing & authentication

Signing & authentication

Signed JSON endpoints carry appKey, timestamp, nonce and sign in the request body and validate the timestamp window and request replay. Use appSecret only on the server to calculate the signature; never transmit it. Generate fresh authentication parameters when retrying.

appKeystringRequired

Merchant application identifier

timestampintegerRequired

Unix timestamp in milliseconds, within a ±15-minute window

noncestringRequired

A fresh random string per request, up to 256 characters, excluding &, = and control characters

signstringRequired

Lowercase hexadecimal MD5 signature

Exclude sign, add appSecret, skip empty strings and null, and retain 0 and false.
Sort field names in ascending order and join key=value pairs with &. Do not append a trailing & or URL-encode the values.
Hash the UTF-8 string with MD5, output lowercase hexadecimal, then add sign to the original request body.

Signing objects and arrays

Objects and arrays enter the signature as compact JSON. Match Go encoding/json serialisation: sort object keys, preserve array order, and account for character escaping and number formatting. Do not use a plain object-to-string conversion.

Encrypted payload mode

For encrypted payloads, send appKey, sKey and sIv headers together. Payloads use AES-CBC; the key and IV use RSA PKCS#1 v1.5 encryption. Confirm public-key configuration before integrating. The example above demonstrates signed JSON mode.

File upload authentication

Use multipart/form-data with required text fields appKey, timestamp and sign. nonce is optional and must follow the string rules when supplied. Sign sorted non-empty text fields except sign, together with appSecret; file contents are excluded. Timestamps allow a ±15-minute window; do not resend the same signature. Send one value per text field and no URL query parameters. tagIds currently accepts one ID as text.

04 / API reference

API reference

Choose an endpoint for your workflow. Expand it for its request URL, authentication mode and business fields.

24 endpoints

POSTCreate an individual payment/v1/tf/order/create

Submit a merchant payment reference in orderNo and details for one payment. Supply beneficiary, bank and purpose fields required by the payment product.

Signed JSONapplication/json

https://api.example.com/v1/tf/order/create

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

orderNostringRequired
extstringOptional
transferTypeinteger · 1 2 3Required
transferSegmentinteger · 1 2Required
sourceCurrencyTypeinteger · 1 2 3Required
sourceCurrencystringRequired
destinationCurrencyTypeinteger · 1 2 3Required
destinationCurrencystringRequired
cardNumberstringRequired
amountnumberRequired
notifyUrlstringOptional
remarkstringOptional
channelinteger · 1 2Required
customerIdstringRequired
firstNamestringRequired
lastNamestringRequired
countrystringOptional
citystringOptional
addressstringOptional
postcodestringOptional
sortCodestringOptional
routingNumberstringOptional
bsbCodestringOptional
ifscstringOptional
ibanstringOptional
bicstringOptional
clabestringOptional

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList payment orders/v1/tf/order/list

Retrieve paginated payment orders and status. Filter by merchant order number using merOrderNo to obtain the system order ID.

Signed JSONapplication/json

https://api.example.com/v1/tf/order/list

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

pageintegerRequired
pageSizeintegerRequired
merOrderNostringOptional
sourceCurrencyTypeintegerOptional
cardNumberstringOptional

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTRetrieve payment details/v1/tf/order

Pass the system order ID in id to retrieve payment details. The merchant-supplied orderNo is not the system id.

Signed JSONapplication/json

https://api.example.com/v1/tf/order

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

idintegerRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList payout products/v1/tf/transfer_product/list

Retrieve available payout products and configuration.

Signed JSONapplication/json

https://api.example.com/v1/tf/transfer_product/list

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

pageintegerRequired
pageSizeintegerRequired
namestringOptional
statusintegerOptional

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTRetrieve a payout product/v1/tf/transfer_product

Retrieve payout product details by product ID.

Signed JSONapplication/json

https://api.example.com/v1/tf/transfer_product

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

idintegerRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTSubmit customer registration/v1/va/user/registration/create

Submit customer verification information, including individual, business, legal representative and beneficial owner details required for the customer type.

Signed JSONapplication/json

https://api.example.com/v1/va/user/registration/create

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTUpdate a registration/v1/va/user/registration/update

Update registration information using vaUserId.

Signed JSONapplication/json

https://api.example.com/v1/va/user/registration/update

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTRetrieve a registration/v1/va/user/registration/detail

Retrieve customer registration information and review status.

Signed JSONapplication/json

https://api.example.com/v1/va/user/registration/detail

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

vaUserIdstringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList customers/v1/va/user/list

Retrieve a paginated list of registered collection customers.

Signed JSONapplication/json

https://api.example.com/v1/va/user/list

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTApply for a collection account/v1/va/account/apply

Submit a collection account application for a registered customer and confirm activation from the review result. Accounts, currencies and documentation depend on business configuration.

Signed JSONapplication/json

https://api.example.com/v1/va/account/apply

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList collection accounts/v1/va/account/list

Filter collection accounts by account number, currency or status.

Signed JSONapplication/json

https://api.example.com/v1/va/account/list

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTRetrieve an account/v1/va/account/detail

Retrieve account details using vaAccountId.

Signed JSONapplication/json

https://api.example.com/v1/va/account/detail

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

vaAccountIdstringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList collections/v1/va/collection/records/list

Query paginated collection records by currency, date, account and other filters.

Signed JSONapplication/json

https://api.example.com/v1/va/collection/records/list

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTRetrieve a collection/v1/va/collection/records

Retrieve a collection and its supporting-document status using vaCollectionId.

Signed JSONapplication/json

https://api.example.com/v1/va/collection/records

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

vaCollectionIdstringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTSubmit collection documents/v1/va/collection/records/attachment/submit

Submit uploaded file IDs and attachment details for a collection, then query the collection record for subsequent review status.

Signed JSONapplication/json

https://api.example.com/v1/va/collection/records/attachment/submit

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

vaCollectionIdstringRequired
attachmentTypestringRequired
attachmentsstringRequired
unitIdstringRequired
fileIdsstring[]Required
webStoreUrlstringConditional
senderInfoobjectConditional
- companyNamestringRequired
- legalNamestringRequired
- addressstringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTQuery net collection totals/v1/va/collection/records/balance/summary

Summarise net collection amounts by collection account number and currency. This is a receipt statistic, not the available currency account balance.

Signed JSONapplication/json

https://api.example.com/v1/va/collection/records/balance/summary

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

accountNostringRequired
currencystringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTQuery currency account balances/v1/merchant/fundPool/balance

Query the current merchant currency accounts, including identifiers, account balances, frozen and available balances, and status. Filter by currency if required.

Signed JSONapplication/json

https://api.example.com/v1/merchant/fundPool/balance

Business request fields

Also include appKey, timestamp, nonce and sign; see signing and authentication.

currencystringOptional

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList exchange rates/v1/tf/quote/all

Retrieve the exchange-rate quote list.

No signing parametersapplication/json

https://api.example.com/v1/tf/quote/all

Business request fields

No business request fields. Send an empty JSON object.

POSTQuery a currency-pair rate/v1/tf/quote

Query a rate for the source and target currencies. This query does not create a conversion transaction or move funds.

No signing parametersapplication/json

https://api.example.com/v1/tf/quote

Business request fields

sourceCurrencystringRequired
destinationCurrencystringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList countries/v1/tf/country/list

Retrieve destination country codes and names.

No signing parametersapplication/json

https://api.example.com/v1/tf/country/list

Business request fields

No business request fields. Send an empty JSON object.

POSTQuery payment currencies and channel partners/v1/tf/currency/partner

Query supported currencies and channel partners for a country and channel type.

No signing parametersapplication/json

https://api.example.com/v1/tf/currency/partner

Business request fields

typestringRequired
countrystringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTQuery payment business modes/v1/tf/business/mode

Query supported payment business modes for the specified country and type.

No signing parametersapplication/json

https://api.example.com/v1/tf/business/mode

Business request fields

countrystringRequired
typestringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTList banks/v1/tf/bank/list

Retrieve bank codes and names for a country.

No signing parametersapplication/json

https://api.example.com/v1/tf/bank/list

Business request fields

countrystringRequired

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

POSTUpload a file/v1/file/upload

Upload a file using multipart/form-data. Sign non-empty text fields; file contents are excluded.

Signed multipartmultipart/form-data

https://api.example.com/v1/file/upload

Business request fields

filebinaryRequired
fileTypeintegerOptional
tagIdsstringOptional

Conditional requirements depend on customer type, payment method and integration configuration. Expand objects to inspect nested fields.

05 / Async notifications

Async notifications

Configure the payment notification URL and verify transaction status through order queries.

Set your receiving URL

Provide notifyUrl when creating a payment to receive status notifications. Confirm payloads, source verification and response requirements during integration, and retain order queries for result reconciliation.

https://merchant.example.com/webhooks/okwire

Notification verification and status reconciliation

Verify the notification source and handle duplicates using order identifiers and business status. The order detail endpoint requires the system order ID. If only a merchant order number is available, filter the list with merOrderNo to obtain the ID before reconciling the result.

Query payout and collection status

BUILD WITH OK WIRE

Discuss API integration

Complete merchant onboarding and access configuration to integrate cross-border payment services.

Open the business console

Cross-border payment APIs,integrated with your workflows.

API integration workflow

Prepare your access

Configure authentication

Make your first query

Connect your workflow

Query account balances

Signing & authentication

API reference

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Business request fields

Async notifications

Set your receiving URL

Notification verification and status reconciliation

Discuss API integration