OK WIRE DEVELOPERS

Build your nextpayment experience.

Connect global payouts, collection accounts and balance queries to your product with the OK Wire API.

REST APIJSONServer-to-server

Illustrative flowREST / 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

Start with one request.

Set up your integration, then connect your business workflow.

01
Prepare your access
Complete merchant onboarding and obtain your appKey, appSecret and environment details.
Open console
02
Configure authentication
Store credentials on your server. Confirm IP settings and whether encrypted payloads are needed.
Signing & authentication
03
Make your first query
Use a balance query to verify signing, connectivity and response handling.
Your first request
04
Connect your workflow
Integrate payouts or collections, then handle order status and asynchronous results.
Explore the API

02 / Your first request

Your first request

Learn the request format with a read-only fund-pool balance query. Run the example on your server; this page does not send API 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 authentication fields in the request body. Use appSecret locally to compute the signature; never send it in the request.

appKeystringRequired

Merchant application identifier

timestampintegerRequired

Unix timestamp in milliseconds

noncestringRequired

A fresh random string for each request

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

Uploads use multipart/form-data with required text fields appKey, timestamp and sign. Sign all non-empty text fields except sign, together with appSecret; exclude file contents. The timestamp allows a ±15-minute window. tagIds currently accepts a single 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 a payout/v1/tf/order/create

Submit payout details and a merchant order number. Recipient requirements depend on destination and payment method.

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 payouts/v1/tf/order/list

Retrieve paginated payout orders and their processing status.

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 a payout/v1/tf/order

Retrieve an order using its system ID, rather than the merchant orderNo.

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.

POSTRegister a customer/v1/va/user/registration/create

Submit customer KYC information. Individual, company, legal representative and beneficial owner details depend on KYC 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 an account/v1/va/account/apply

Apply for a collection account for a registered customer. Required information and currencies depend on your 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 supporting documents/v1/va/collection/records/attachment/submit

Submit uploaded file IDs and attachment information for review.

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.

POSTSummarise collection amounts/v1/va/collection/records/balance/summary

Summarise net collection amounts by account and currency. This is not the available 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.

POSTRetrieve fund-pool balances/v1/merchant/fundPool/balance

Retrieve the current merchant’s balance, frozen amount and available balance, optionally filtered by currency.

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.

POSTRetrieve a currency quote/v1/tf/quote

Retrieve an exchange rate for a source and destination currency.

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.

POSTList currencies and partners/v1/tf/currency/partner

Retrieve supported currencies and 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.

POSTList business modes/v1/tf/business/mode

Retrieve supported modes for a country and business 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

Provide a notification URL for payout orders and use order queries to confirm the result.

Set your receiving URL

Payout creation accepts notifyUrl. Confirm notification fields, signature verification and retry arrangements during integration.

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

Handle results reliably

Deduplicate by order identifier and verify the notification source before updating state. Use query endpoints to confirm duplicate or uncertain results.

Query payout and collection status

BUILD WITH OK WIRE

Ready to connect your next workflow?

Start with merchant onboarding and connect your product to global payments.

Open console

Build your nextpayment experience.

Start with one request.

Prepare your access

Configure authentication

Make your first query

Connect your workflow

Your first request

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

Handle results reliably

Ready to connect your next workflow?