{ "components": { "schemas": { "APIPaymentInstruction": { "properties": { "aba_routing_code": { "description": "American Bankers Association routing code. Methods: ACH\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: N/A\n- `ACH`: <= 9, required\n- `US_CHECK`: N/A", "type": "string" }, "amount": { "description": "Payment amount with maximum of 2 decimal places.\n\nMinimum 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.", "format": "decimal", "pattern": "^\\d{1,18}(?:\\.\\d{1,2})?$", "type": "string" }, "beneficiary_account": { "description": "Account number of beneficiary.\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 34, required\n- `ACH`: <= 17, required\n- `US_CHECK`: N/A", "type": "string" }, "beneficiary_alias_token": { "description": "Beneficiary alias token which can be used instead of IBAN.\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: <= 12, optional\n- `WIRE`: N/A\n- `ACH`: N/A\n- `US_CHECK`: N/A", "type": "string" }, "beneficiary_city": { "description": "City of beneficiary\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 35, required\n- `ACH`: N/A\n- `US_CHECK`: <= 35, required", "type": "string" }, "beneficiary_country_code": { "description": "Country of beneficiary.\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 2, required\n- `ACH`: N/A\n- `US_CHECK`: <= 2, required", "type": "string" }, "beneficiary_iban": { "description": "International bank account number.\n\nTransfer methods:\n- `SEPA`: <= 34, required\n- `INTERNAL`: <= 34, optional\n- `WIRE`: N/A\n- `ACH`: N/A\n- `US_CHECK`: N/A", "type": "string" }, "beneficiary_name": { "description": "Name of beneficiary.\n\nTransfer methods:\n- `SEPA`: <= 70, required\n- `INTERNAL`: N/A\n- `WIRE`: <= 70, required\n- `ACH`: <= 22, required\n- `US_CHECK`: <= 70, required", "type": "string" }, "beneficiary_postal_code": { "description": "Postal code of beneficiary.\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 16, required\n- `ACH`: N/A\n- `US_CHECK`: <= 16, required", "type": "string" }, "beneficiary_region_state": { "description": "Region of beneficiary.\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: N/A\n- `ACH`: N/A\n- `US_CHECK`: <= 20, optional", "type": "string" }, "beneficiary_street": { "description": "Street address of beneficiary\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 70, required\n- `ACH`: N/A\n- `US_CHECK`: <= 70, required", "type": "string" }, "bic_code": { "description": "Bank identifier code of beneficiary\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 11, required\n- `ACH`: N/A\n- `US_CHECK`: N/A", "type": "string" }, "currency": { "description": "Currency of payment\n- `SEPA` - EUR\n- `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\n- `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\n- `ACH` - USD\n- `US_CHECK` - USD", "type": "string" }, "group": { "description": "Your identifier of group of payments", "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" }, "intermediary_bank_bic_code": { "description": "Bank identifier code of intermediary bank\n\nTransfer methods:\n- `SEPA`: N/A\n- `INTERNAL`: N/A\n- `WIRE`: <= 11, optional\n- `ACH`: N/A\n- `US_CHECK`: N/A", "type": "string" }, "note_for_beneficiary": { "description": "Note for beneficiary.\n\nTransfer methods:\n- `SEPA`: <= 140, optional\n- `INTERNAL`: <= 140, optional\n- `WIRE`: <= 63, optional\n- `ACH`: <= 80, optional\n- `US_CHECK`: <= 80, optional", "nullable": true, "type": "string" }, "reference": { "description": "Identifier of payment. **Must** be unique to your account.", "maxLength": 40, "type": "string" }, "transfer_method": { "allOf": [ { "$ref": "#/components/schemas/TransferMethodEnum" } ], "description": "Transfer method of payment\n\n* `SEPA` - SEPA transfer\n* `INTERNAL` - Yoursafe transfer\n* `WIRE` - International wire\n* `ACH` - ACH transfer\n* `US_CHECK` - US check transfer" } }, "required": [ "amount", "currency", "group", "reference", "transfer_method" ], "type": "object" }, "CurrencyEnum": { "description": "* `EUR` - EUR", "enum": [ "EUR" ], "type": "string" }, "TransferMethodEnum": { "description": "* `SEPA` - SEPA transfer\n* `INTERNAL` - Yoursafe transfer\n* `WIRE` - International wire\n* `ACH` - ACH transfer\n* `US_CHECK` - US check transfer", "enum": [ "SEPA", "INTERNAL", "WIRE", "ACH", "US_CHECK" ], "type": "string" }, "VoucherCreationResult": { "oneOf": [ { "properties": { "success": { "not": { "enum": [ false ] }, "type": "boolean" }, "voucher_url": { "format": "uri", "type": "string" } }, "required": [ "success", "voucher_url" ], "type": "object" }, { "properties": { "error": { "type": "string" }, "success": { "not": { "enum": [ true ] }, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } ] }, "VoucherInstruction": { "properties": { "amount": { "description": "Monetary value of the voucher. Min 0.50, Max 2500.00.", "format": "decimal", "pattern": "^\\d{1,4}(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyEnum" } ], "description": "Currency of the voucher.\n\n* `EUR` - EUR" }, "description": { "description": "Description or note for the voucher. Shown to the recipient when the voucher is redeemed.", "maxLength": 120, "type": "string" }, "idempotency_key": { "description": "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.", "maxLength": 40, "type": "string" } }, "required": [ "amount", "currency", "idempotency_key" ], "type": "object" } }, "securitySchemes": { "basicAuth": { "scheme": "basic", "type": "http" } } }, "info": { "description": "# Getting Started\n\nThis API currently provides:\n\n- Mass Payments\n - Validate mass payment instructions\n - Upload mass payment instructions\n- Voucher Creation\n - Create Yourcash vouchers\n\n## Mass Payments API\n\nThe Yoursafe Mass Payments API lets you create bulk payment instructions programmatically.\n\nIt is designed for businesses that need to send payouts to multiple recipients, such as:\n\n- Marketplaces\n- Affiliate platforms\n- Payroll or partner payout systems\n\nUsing the API, you can:\n\n- Submit multiple payment instructions in a single request\n- Automate payout workflows\n- Integrate payments directly into your system\n\nImportant: The API does not execute payments directly. It only creates payment instructions, which must be approved in\nthe Yoursafe interface before funds are transferred.\n\n## How the Approval Flow Works\n\nAfter submission:\n\n1. Payment instructions are created via API\n2. They appear in Yoursafe Business under Make transfer -> API mass payment\n3. A user must review and approve them manually\n4. Only then are payments executed\n\n## Generating and Managing API Keys\n\nTo access the API, you need an API key.\n\n### Where to find it\n\n1. Log in to your Yoursafe Business account\n2. Open User Profile\n3. Scroll down to API keys\n4. Click Add\n5. Give your key a name\n6. Note the generated key and keep it safe\n\nImportant: The API key is shown only once and cannot be retrieved later. Make sure to store keys securely, for example\nin a secrets manager.\n\n## Authentication\n\nThe API uses HTTP Basic Authentication.\n\n### API Key format\n\nEach API key consists of two parts:\n\n```text\n:\n```\n\nExample:\n\n```text\nY42X3JP9:VtwguJNDpk6B6euDqnLqZNaz4fLm32xU\n```\n\n### How to use the key\n\n- Username: part before `:`\n- Password: part after `:`\n\nFor each request:\n\n1. Combine `username:password`\n2. Encode using Base64\n3. Send in the header: `Authorization: Basic `\n\nExample request:\n\n```bash\ncurl -X POST https://business.yoursafe.com/mass-payment-api/upload \\\n -H \"Authorization: Basic \" \\\n -H \"Content-Type: application/json\" \\\n -d '{ ... }'\n```\n\n## Key Concepts\n\n### Batch\n\nA group of payment instructions submitted together via API.\n\n### Instruction\n\nA single payment instruction, for example one transfer.\n\n### Approval Flow\n\nPayments must be approved in the Yoursafe UI before execution.\n\n## Payment Status Tracking\n\nThe API currently supports creating payment instructions only.\n\nIt does not currently provide:\n\n- Payment status endpoints\n- Webhook or callback notifications\n- Real-time synchronization of approval or deletion actions\n\nIf status synchronization is required, we recommend implementing a reconciliation process using exported payout reports\nand unique external references from your platform.\n\n## Security Best Practices\n\n- Never expose API keys in frontend code\n- Do not commit keys to source control\n- Use separate keys for test and production\n- Rotate keys regularly\n- Revoke compromised keys immediately\n", "title": "Yoursafe API", "version": "" }, "openapi": "3.0.3", "paths": { "/mass-payment-api/create-vouchers": { "post": { "description": "\nCreate a single Yourcash voucher funded from your Yoursafe account. Despite the endpoint name, one request creates\nexactly one voucher.\n\nCreating vouchers requires basic HTTP authentication with the same\n[API key](/user-profile#content-api-keys) as the mass payment endpoints, and has to be enabled\nfor your account. If it is not, every request is answered with `403 Forbidden`.\n\n## Response\n\n`200 OK` is returned both when the voucher was created and when creating it was refused for a business reason, so\nalways check the `success` field:\n\n- `success` is `true` - the response also contains `voucher_url`, the link the recipient opens to redeem the voucher\n- `success` is `false` - the response contains `error` with the reason, for example insufficient funds\n\nInvalid input is answered with `400 Bad Request` and a body mapping each rejected field to a list of messages, for\nexample `{\"amount\": [\"Ensure this value is greater than or equal to 0.50.\"]}`.\n\n## When the voucher becomes redeemable\n\nA successful API response does not guarantee that the voucher is immediately redeemable.\n\nThe voucher amount is debited from your account as soon as the request succeeds, but the voucher itself is funded by a\nseparate internal transfer. Until that transfer has been processed, `voucher_url` already works, yet the voucher shows\na zero balance and cannot be redeemed.\n\nThe transfer is usually processed within seconds. It can, however, be held for transaction monitoring, and is then\nreleased only once Yoursafe has reviewed it - for as long as that takes, the voucher keeps showing a zero balance.\nThere is no endpoint for querying voucher status.\n\n## Idempotency\n\n`idempotency_key` makes voucher creation safe to retry. It is scoped to your account:\n\n- repeating a request with the same `idempotency_key` and the same `amount`, `currency` and `description` returns the\n original voucher, without creating a second voucher and without debiting your account again\n- reusing an `idempotency_key` with any different value returns `200 OK` with `success` set to `false`\n\nThe values are compared after validation: amounts are compared as decimal values, and leading and trailing whitespace\nis removed from `description`. An omitted `description`, an empty `description`, and a whitespace-only `description`\nare therefore equivalent.\n\n## Currency\n\nVouchers are issued in EUR. If your account is held in another currency, the EUR amount is converted at the current\nexchange rate and the converted amount is debited from your account.\n", "operationId": "create_vouchers_create", "requestBody": { "content": { "application/json": { "examples": { "Case-error--idempotency-key-reused": { "description": "\nPassed an `idempotency_key` of an already created voucher, but with a different `amount`.\n\nRepeating a request with the same `idempotency_key` **and** the same `amount`, `currency` and `description` returns the\noriginal voucher instead, without creating or debiting anything again.\n", "summary": "Idempotency key reused with different parameters", "value": { "amount": "30.00", "currency": "EUR", "description": "Affiliate payout October", "idempotency_key": "b8f1c0de-5d3a-4f7b-9c21-6a0e4d7f1a55" } }, "Case-error--insufficient-funds": { "description": "Requested voucher amount exceeds the available balance of the account", "summary": "Insufficient funds", "value": { "amount": "2500.00", "currency": "EUR", "idempotency_key": "6c4d2b91-8e07-4a3f-b5d6-19f2c8a04e73" } }, "Case-valid": { "description": "Voucher created and debited from the account", "summary": "Valid request", "value": { "amount": "25.00", "currency": "EUR", "description": "Affiliate payout October", "idempotency_key": "b8f1c0de-5d3a-4f7b-9c21-6a0e4d7f1a55" } } }, "schema": { "$ref": "#/components/schemas/VoucherInstruction" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Case-error--idempotency-key-reused": { "description": "\nPassed an `idempotency_key` of an already created voucher, but with a different `amount`.\n\nRepeating a request with the same `idempotency_key` **and** the same `amount`, `currency` and `description` returns the\noriginal voucher instead, without creating or debiting anything again.\n", "summary": "Idempotency key reused with different parameters", "value": { "error": "Create voucher requested with same idempotency_key but different parameters", "success": false } }, "Case-error--insufficient-funds": { "description": "Requested voucher amount exceeds the available balance of the account", "summary": "Insufficient funds", "value": { "error": "Insufficient funds", "success": false } }, "Case-valid": { "description": "Voucher created and debited from the account", "summary": "Valid request", "value": { "success": true, "voucher_url": "https://you.yoursafe.com/app/deep?data=eyJxci1jb21tYW5kIjogInJlZGVlbXZvdWNoZXIiLCAidm91Y2hlcl90b2tlbiI6ICIzZjJiOWExYy03ZDRlLTVmOGEtOWI2Yy0yZTFkMGE4ZjRjNzMuWGs3UXAyUnQ5TG00VmIxWmM4TnMifQ==" } } }, "schema": { "$ref": "#/components/schemas/VoucherCreationResult" } } }, "description": "" }, "400": { "content": { "application/json": { "examples": { "Case-invalid--amount-above-maximum": { "description": "Passed amount higher than the maximum voucher amount", "summary": "Amount above the maximum", "value": { "amount": [ "Ensure this value is less than or equal to 2500.00." ] } }, "Case-invalid--amount-below-minimum": { "description": "Passed amount lower than the minimum voucher amount", "summary": "Amount below the minimum", "value": { "amount": [ "Ensure this value is greater than or equal to 0.50." ] } }, "Case-invalid--blank-idempotency-key": { "description": "\nPassed an empty `idempotency_key`.\n\nThe field must be present and must not be blank; a value consisting only of whitespace is treated as blank.\n", "summary": "Blank idempotency key", "value": { "idempotency_key": [ "This field may not be blank." ] } }, "Case-invalid--unsupported-currency": { "description": "Passed 'USD' as voucher currency; vouchers are issued in EUR only", "summary": "Unsupported voucher currency", "value": { "currency": [ "\"USD\" is not a valid choice." ] } } }, "schema": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" } } }, "description": "" }, "403": { "content": { "application/json": { "examples": { "Case-invalid--voucher-api-not-enabled": { "description": "The account is not allowed to create vouchers", "summary": "Voucher creation not enabled", "value": { "error": "Your account is not allowed to create vouchers. Please contact support.", "success": false } } }, "schema": { "$ref": "#/components/schemas/VoucherCreationResult" } } }, "description": "" } }, "security": [ { "basicAuth": [] } ], "summary": "Voucher Creation Request", "tags": [ "create-vouchers" ] } }, "/mass-payment-api/upload": { "post": { "description": "\nUploading mass payments via this API requires basic HTTP authentication. For this authentication you need to\n[generate API key](/user-profile#content-api-keys).\n\nUploaded mass payment is JSON containing list of dictionaries, each dictionary representing one transfer.\n\nPlease note that there is a **limit of 5,000** unconfirmed\ninstructions. If this limit is reached, the API will not accept more instructions, until the current ones are\nprocessed by Yoursafe user.\n\n## Response\n\nA valid request is answered with `200 OK` and `{\"success\": true}`. The instructions are only created, not executed -\nthey have to be approved in Yoursafe Business under Make transfer -> API mass payment.\n\nRejected requests are answered with `400 Bad Request`. The body maps every failing instruction to its field errors,\nwhere `item #1` is the first instruction of the request, for example `{\"item #1\": {\"amount\": [\"Too low amount.\"]}}`.\nErrors that are not tied to a single instruction, such as exceeding the limit of unconfirmed instructions, are returned\nas a list of messages instead.\n", "operationId": "upload_create", "requestBody": { "content": { "application/json": { "examples": { "Case-valid": { "description": "No errors found in the request", "summary": "Valid request", "value": [ { "amount": "10.10", "beneficiary_iban": "NL46ABNA7000001046", "beneficiary_name": "Jane Doe", "currency": "EUR", "group": "mass-payment-group-no-1", "reference": "test reference", "transfer_method": "SEPA" } ] } }, "schema": { "items": { "$ref": "#/components/schemas/APIPaymentInstruction" }, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Case-valid": { "description": "No errors found in the request", "summary": "Valid request", "value": { "success": true } } }, "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "" }, "400": { "content": { "application/json": { "examples": { "Case-invalid--amount-below-minimum": { "description": "Passed amount lower than the minimum transfer amount of 0.50 EUR", "summary": "Amount below the minimum", "value": { "item #1": { "amount": [ "Too low amount." ] } } }, "Case-invalid--duplicate-reference": { "description": "Passed reference which was already used for different transfer within the API mass payment", "summary": "Duplicate reference", "value": { "item #1": { "reference": [ "Duplicate unique identifier" ] }, "item #2": { "reference": [ "Duplicate unique identifier" ] } } }, "Case-invalid--more-errors": { "description": "Request with errors in second and third items:\n- SEPA transfer without specifying IBAN\n- Passed amount 'ten point five', currency 'ABC'\n", "summary": "Combination of several input errors", "value": { "item #2": { "beneficiary_iban": [ "Beneficiary IBAN is missing." ] }, "item #3": { "amount": [ "A valid number is required." ], "currency": [ "\"ABC\" is not a valid choice." ] } } }, "Case-invalid--wrong-currency": { "description": "Passed 'USD' as instructed currency for SEPA transfer", "summary": "Invalid instructed currency", "value": { "item #1": { "currency": [ "Invalid currency." ] } } } }, "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "" } }, "security": [ { "basicAuth": [] } ], "summary": "Upload mass payment JSON", "tags": [ "upload" ] } }, "/mass-payment-api/validate": { "post": { "description": "\nValidate data to be uploaded as mass payment. Nothing is created, the request is only checked.\n\nUploading mass payments via this API requires basic HTTP authentication. For this authentication you need to\n[generate API key](/user-profile#content-api-keys).\n\nUploaded mass payment is JSON containing list of dictionaries, each dictionary representing one transfer.\n\nPlease note that there is a **limit of 5,000** unconfirmed\ninstructions. If this limit is reached, the API will not accept more instructions, until the current ones are\nprocessed by Yoursafe user.\n\n## Response\n\nA valid request is answered with `200 OK` and `{\"success\": true}`, meaning the very same body would be accepted by\n`upload`.\n\nRejected requests are answered with `400 Bad Request`. The body maps every failing instruction to its field errors,\nwhere `item #1` is the first instruction of the request, for example `{\"item #1\": {\"amount\": [\"Too low amount.\"]}}`.\nErrors that are not tied to a single instruction, such as exceeding the limit of unconfirmed instructions, are returned\nas a list of messages instead.\n", "operationId": "validate_create", "requestBody": { "content": { "application/json": { "examples": { "Case-valid": { "description": "No errors found in the request", "summary": "Valid request", "value": [ { "amount": "10.10", "beneficiary_iban": "NL46ABNA7000001046", "beneficiary_name": "Jane Doe", "currency": "EUR", "group": "mass-payment-group-no-1", "reference": "test reference", "transfer_method": "SEPA" } ] } }, "schema": { "items": { "$ref": "#/components/schemas/APIPaymentInstruction" }, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Case-valid": { "description": "No errors found in the request", "summary": "Valid request", "value": { "success": true } } }, "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "" }, "400": { "content": { "application/json": { "examples": { "Case-invalid--amount-below-minimum": { "description": "Passed amount lower than the minimum transfer amount of 0.50 EUR", "summary": "Amount below the minimum", "value": { "item #1": { "amount": [ "Too low amount." ] } } }, "Case-invalid--duplicate-reference": { "description": "Passed reference which was already used for different transfer within the API mass payment", "summary": "Duplicate reference", "value": { "item #1": { "reference": [ "Duplicate unique identifier" ] }, "item #2": { "reference": [ "Duplicate unique identifier" ] } } }, "Case-invalid--more-errors": { "description": "Request with errors in second and third items:\n- SEPA transfer without specifying IBAN\n- Passed amount 'ten point five', currency 'ABC'\n", "summary": "Combination of several input errors", "value": { "item #2": { "beneficiary_iban": [ "Beneficiary IBAN is missing." ] }, "item #3": { "amount": [ "A valid number is required." ], "currency": [ "\"ABC\" is not a valid choice." ] } } }, "Case-invalid--wrong-currency": { "description": "Passed 'USD' as instructed currency for SEPA transfer", "summary": "Invalid instructed currency", "value": { "item #1": { "currency": [ "Invalid currency." ] } } } }, "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "" } }, "security": [ { "basicAuth": [] } ], "summary": "Verify mass payment JSON for upload", "tags": [ "validate" ] } } }, "servers": [ { "description": "Production", "url": "https://business.yoursafe.com" } ], "tags": [ { "name": "upload" }, { "name": "validate" }, { "name": "create-vouchers" } ] }