Yoursafe · Mass Payments
Yoursafe

Mass Payments API

OpenAPI
  • https://business.yoursafe.com

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.