Yoursafe · Mass Payments API
Yoursafe

Mass Payments API

OpenAPI
  • https://business.yoursafe.com

Getting Started

This API currently provides:

  • Mass Payments
  • Validate mass payment instructions
  • Upload mass payment instructions
  • Voucher Creation
  • Create Yourcash vouchers

Mass Payments API

The Yoursafe Mass Payments API lets you create bulk payment instructions programmatically.

It is designed for businesses that need to send payouts to multiple recipients, such as:

  • Marketplaces
  • Affiliate platforms
  • Payroll or partner payout systems

Using the API, you can:

  • Submit multiple payment instructions in a single request
  • Automate payout workflows
  • Integrate payments directly into your system

Important: The API does not execute payments directly. It only creates payment instructions, which must be approved in the Yoursafe interface before funds are transferred.

How the Approval Flow Works

After submission:

  1. Payment instructions are created via API
  2. They appear in Yoursafe Business under Make transfer -> API mass payment
  3. A user must review and approve them manually
  4. Only then are payments executed

Generating and Managing API Keys

To access the API, you need an API key.

Where to find it

  1. Log in to your Yoursafe Business account
  2. Open User Profile
  3. Scroll down to API keys
  4. Click Add
  5. Give your key a name
  6. Note the generated key and keep it safe

Important: The API key is shown only once and cannot be retrieved later. Make sure to store keys securely, for example in a secrets manager.

Authentication

The API uses HTTP Basic Authentication.

API Key format

Each API key consists of two parts:

Example:

How to use the key

  • Username: part before :
  • Password: part after :

For each request:

  1. Combine username:password
  2. Encode using Base64
  3. Send in the header: Authorization: Basic <base64-encoded-value>

Example request:

<username>:<password>

Key Concepts

Batch

A group of payment instructions submitted together via API.

Instruction

A single payment instruction, for example one transfer.

Approval Flow

Payments must be approved in the Yoursafe UI before execution.

Payment Status Tracking

The API currently supports creating payment instructions only.

It does not currently provide:

  • Payment status endpoints
  • Webhook or callback notifications
  • Real-time synchronization of approval or deletion actions

If status synchronization is required, we recommend implementing a reconciliation process using exported payout reports and unique external references from your platform.

Security Best Practices

  • Never expose API keys in frontend code
  • Do not commit keys to source control
  • Use separate keys for test and production
  • Rotate keys regularly
  • Revoke compromised keys immediately

Upload mass payment JSON

POST https://business.yoursafe.com/mass-payment-api/upload
content-type: application/json

[
  {
    "amount": "10.10",
    "beneficiary_iban": "NL46ABNA7000001046",
    "beneficiary_name": "Jane Doe",
    "currency": "EUR",
    "group": "mass-payment-group-no-1",
    "reference": "test reference",
    "transfer_method": "SEPA"
  }
]
POST/mass-payment-api/upload

Uploading mass payments via this API requires basic HTTP authentication. For this authentication you need to generate API key.

Uploaded mass payment is JSON containing list of dictionaries, each dictionary representing one transfer.

Please note that there is a limit of 5,000 unconfirmed instructions. If this limit is reached, the API will not accept more instructions, until the current ones are processed by Yoursafe user.

Response

A valid request is answered with 200 OK and {"success": true}. The instructions are only created, not executed - they have to be approved in Yoursafe Business under Make transfer -> API mass payment.

Rejected requests are answered with 400 Bad Request. The body maps every failing instruction to its field errors, where item #1 is the first instruction of the request, for example {"item #1": {"amount": ["Too low amount."]}}. Errors that are not tied to a single instruction, such as exceeding the limit of unconfirmed instructions, are returned as a list of messages instead.

Request bodyrequired

application/json · array

aba_routing_codestring

American Bankers Association routing code. Methods: ACH

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: N/A
  • ACH: <= 9, required
  • US_CHECK: N/A
amountstringrequired
  • Payment amount with maximum of 2 decimal places.
  • Minimum amount is 0.50 EUR, 0.50 GBP, 0.50 USD. For any other currency the minimum is the equivalent of the minimum in your account currency, converted by the current exchange rate. No maximum amount is validated here; the available balance is checked when the mass payment is approved in Yoursafe Business.
beneficiary_accountstring

Account number of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 34, required
  • ACH: <= 17, required
  • US_CHECK: N/A
beneficiary_alias_tokenstring

Beneficiary alias token which can be used instead of IBAN.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: <= 12, optional
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: N/A
beneficiary_citystring

City of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 35, required
  • ACH: N/A
  • US_CHECK: <= 35, required
beneficiary_country_codestring

Country of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 2, required
  • ACH: N/A
  • US_CHECK: <= 2, required
beneficiary_ibanstring

International bank account number.

Transfer methods:

  • SEPA: <= 34, required
  • INTERNAL: <= 34, optional
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: N/A
beneficiary_namestring

Name of beneficiary.

Transfer methods:

  • SEPA: <= 70, required
  • INTERNAL: N/A
  • WIRE: <= 70, required
  • ACH: <= 22, required
  • US_CHECK: <= 70, required
beneficiary_postal_codestring

Postal code of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 16, required
  • ACH: N/A
  • US_CHECK: <= 16, required
beneficiary_region_statestring

Region of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: <= 20, optional
beneficiary_streetstring

Street address of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 70, required
  • ACH: N/A
  • US_CHECK: <= 70, required
bic_codestring

Bank identifier code of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 11, required
  • ACH: N/A
  • US_CHECK: N/A
currencystringrequired

Currency of payment

  • SEPA - EUR
  • INTERNAL - AED, AFN, ARS, AUD, BAM, BDT, BHD, BND, BRL, BWP, BYN, CAD, CHF, CLP, CNY, COP, CZK, DJF, DKK, DOP, EGP, ETB, EUR, GBP, GEL, HKD, HUF, IDR, ILS, INR, ISK, JOD, JPY, KES, KMF, KRW, KWD, KZT, LBP, LKR, MAD, MOP, MUR, MVR, MWK, MXN, MYR, MZN, NOK, NPR, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, SYP, THB, TND, TRY, TWD, TZS, UAH, USD, VES, XCG, XOF, YER, ZAR, ZMW
  • WIRE - AED, AUD, BHD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KES, KWD, MAD, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, THB, TND, TRY, USD, XCG, ZAR
  • ACH - USD
  • US_CHECK - USD
groupstringrequired

Your identifier of group of payments

intermediary_bank_bic_codestring

Bank identifier code of intermediary bank

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 11, optional
  • ACH: N/A
  • US_CHECK: N/A
note_for_beneficiarystring

Note for beneficiary.

Transfer methods:

  • SEPA: <= 140, optional
  • INTERNAL: <= 140, optional
  • WIRE: <= 63, optional
  • ACH: <= 80, optional
  • US_CHECK: <= 80, optional
referencestringrequired

Identifier of payment. Must be unique to your account.

transfer_methodSEPA | INTERNAL | WIRE | ACH | US_CHECKrequired
  • SEPA - SEPA transfer
  • INTERNAL - Yoursafe transfer
  • WIRE - International wire
  • ACH - ACH transfer
  • US_CHECK - US check transfer

Verify mass payment JSON for upload

POST https://business.yoursafe.com/mass-payment-api/validate
content-type: application/json

[
  {
    "amount": "10.10",
    "beneficiary_iban": "NL46ABNA7000001046",
    "beneficiary_name": "Jane Doe",
    "currency": "EUR",
    "group": "mass-payment-group-no-1",
    "reference": "test reference",
    "transfer_method": "SEPA"
  }
]
POST/mass-payment-api/validate

Validate data to be uploaded as mass payment. Nothing is created, the request is only checked.

Uploading mass payments via this API requires basic HTTP authentication. For this authentication you need to generate API key.

Uploaded mass payment is JSON containing list of dictionaries, each dictionary representing one transfer.

Please note that there is a limit of 5,000 unconfirmed instructions. If this limit is reached, the API will not accept more instructions, until the current ones are processed by Yoursafe user.

Response

A valid request is answered with 200 OK and {"success": true}, meaning the very same body would be accepted by upload.

Rejected requests are answered with 400 Bad Request. The body maps every failing instruction to its field errors, where item #1 is the first instruction of the request, for example {"item #1": {"amount": ["Too low amount."]}}. Errors that are not tied to a single instruction, such as exceeding the limit of unconfirmed instructions, are returned as a list of messages instead.

Request bodyrequired

application/json · array

aba_routing_codestring

American Bankers Association routing code. Methods: ACH

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: N/A
  • ACH: <= 9, required
  • US_CHECK: N/A
amountstringrequired
  • Payment amount with maximum of 2 decimal places.
  • Minimum amount is 0.50 EUR, 0.50 GBP, 0.50 USD. For any other currency the minimum is the equivalent of the minimum in your account currency, converted by the current exchange rate. No maximum amount is validated here; the available balance is checked when the mass payment is approved in Yoursafe Business.
beneficiary_accountstring

Account number of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 34, required
  • ACH: <= 17, required
  • US_CHECK: N/A
beneficiary_alias_tokenstring

Beneficiary alias token which can be used instead of IBAN.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: <= 12, optional
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: N/A
beneficiary_citystring

City of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 35, required
  • ACH: N/A
  • US_CHECK: <= 35, required
beneficiary_country_codestring

Country of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 2, required
  • ACH: N/A
  • US_CHECK: <= 2, required
beneficiary_ibanstring

International bank account number.

Transfer methods:

  • SEPA: <= 34, required
  • INTERNAL: <= 34, optional
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: N/A
beneficiary_namestring

Name of beneficiary.

Transfer methods:

  • SEPA: <= 70, required
  • INTERNAL: N/A
  • WIRE: <= 70, required
  • ACH: <= 22, required
  • US_CHECK: <= 70, required
beneficiary_postal_codestring

Postal code of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 16, required
  • ACH: N/A
  • US_CHECK: <= 16, required
beneficiary_region_statestring

Region of beneficiary.

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: N/A
  • ACH: N/A
  • US_CHECK: <= 20, optional
beneficiary_streetstring

Street address of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 70, required
  • ACH: N/A
  • US_CHECK: <= 70, required
bic_codestring

Bank identifier code of beneficiary

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 11, required
  • ACH: N/A
  • US_CHECK: N/A
currencystringrequired

Currency of payment

  • SEPA - EUR
  • INTERNAL - AED, AFN, ARS, AUD, BAM, BDT, BHD, BND, BRL, BWP, BYN, CAD, CHF, CLP, CNY, COP, CZK, DJF, DKK, DOP, EGP, ETB, EUR, GBP, GEL, HKD, HUF, IDR, ILS, INR, ISK, JOD, JPY, KES, KMF, KRW, KWD, KZT, LBP, LKR, MAD, MOP, MUR, MVR, MWK, MXN, MYR, MZN, NOK, NPR, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, SYP, THB, TND, TRY, TWD, TZS, UAH, USD, VES, XCG, XOF, YER, ZAR, ZMW
  • WIRE - AED, AUD, BHD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KES, KWD, MAD, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, THB, TND, TRY, USD, XCG, ZAR
  • ACH - USD
  • US_CHECK - USD
groupstringrequired

Your identifier of group of payments

intermediary_bank_bic_codestring

Bank identifier code of intermediary bank

Transfer methods:

  • SEPA: N/A
  • INTERNAL: N/A
  • WIRE: <= 11, optional
  • ACH: N/A
  • US_CHECK: N/A
note_for_beneficiarystring

Note for beneficiary.

Transfer methods:

  • SEPA: <= 140, optional
  • INTERNAL: <= 140, optional
  • WIRE: <= 63, optional
  • ACH: <= 80, optional
  • US_CHECK: <= 80, optional
referencestringrequired

Identifier of payment. Must be unique to your account.

transfer_methodSEPA | INTERNAL | WIRE | ACH | US_CHECKrequired
  • SEPA - SEPA transfer
  • INTERNAL - Yoursafe transfer
  • WIRE - International wire
  • ACH - ACH transfer
  • US_CHECK - US check transfer

Voucher Creation Request

POST https://business.yoursafe.com/mass-payment-api/create-vouchers
content-type: application/json

{
  "amount": "25.00",
  "currency": "EUR",
  "description": "Affiliate payout October",
  "idempotency_key": "b8f1c0de-5d3a-4f7b-9c21-6a0e4d7f1a55"
}
POST/mass-payment-api/create-vouchers

Create a single Yourcash voucher funded from your Yoursafe account. Despite the endpoint name, one request creates exactly one voucher.

Creating vouchers requires basic HTTP authentication with the same API key as the mass payment endpoints, and has to be enabled for your account. If it is not, every request is answered with 403 Forbidden.

Response

200 OK is returned both when the voucher was created and when creating it was refused for a business reason, so always check the success field:

  • success is true - the response also contains voucher_url, the link the recipient opens to redeem the voucher
  • success is false - the response contains error with the reason, for example insufficient funds

Invalid input is answered with 400 Bad Request and a body mapping each rejected field to a list of messages, for example {"amount": ["Ensure this value is greater than or equal to 0.50."]}.

When the voucher becomes redeemable

A successful API response does not guarantee that the voucher is immediately redeemable.

The voucher amount is debited from your account as soon as the request succeeds, but the voucher itself is funded by a separate internal transfer. Until that transfer has been processed, voucher_url already works, yet the voucher shows a zero balance and cannot be redeemed.

The transfer is usually processed within seconds. It can, however, be held for transaction monitoring, and is then released only once Yoursafe has reviewed it - for as long as that takes, the voucher keeps showing a zero balance. There is no endpoint for querying voucher status.

Idempotency

idempotency_key makes voucher creation safe to retry. It is scoped to your account:

  • repeating a request with the same idempotency_key and the same amount, currency and description returns the original voucher, without creating a second voucher and without debiting your account again
  • reusing an idempotency_key with any different value returns 200 OK with success set to false

The values are compared after validation: amounts are compared as decimal values, and leading and trailing whitespace is removed from description. An omitted description, an empty description, and a whitespace-only description are therefore equivalent.

Currency

Vouchers are issued in EUR. If your account is held in another currency, the EUR amount is converted at the current exchange rate and the converted amount is debited from your account.

Request bodyrequired

application/json

amountstringrequired

Monetary value of the voucher. Min 0.50, Max 2500.00.

currencyEURrequired
  • EUR - EUR
descriptionstring

Description or note for the voucher. Shown to the recipient when the voucher is redeemed.

idempotency_keystringrequired

Unique key to ensure idempotency of voucher creation requests. Must not be blank; leading and trailing whitespace is stripped. Any other content is accepted, so use a value that is unique in your system, for example a UUID.