{ "openapi": "3.0.3", "info": { "title": "VALR Business API", "version": "a7dfdf1719" }, "servers": [ { "url": "https://api.valr.com", "description": "Production" } ], "paths": { "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}": { "get": { "operationId": "getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the reference, e.g. `ZAR`.", "example": "ZAR" }, { "name": "referenceCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The reference code returned when the reference was created.", "example": "VPAY-7K2Q9RT" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueDepositReferenceForDisplay" }, "example": { "referenceCode": "VPAY-7K2Q9RT", "currency": "ZAR", "expectedAmount": "1500", "createdAt": 1792742400000, "name": "Thandi Nkosi", "email": "thandi@example.com", "matchedDeposits": [ { "publicId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "amount": "1500", "effectiveDate": "2026-10-23", "creditedAt": 1792746000000, "isOverride": false } ], "matchedDepositCount": 1 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND": { "summary": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND (-15114)", "value": { "code": -15114, "message": "Deposit reference not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ], "summary": "Get a deposit reference", "description": "Returns a deposit reference and the deposits that have been matched to it.", "tags": [ "Deposit references" ] }, "delete": { "operationId": "deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the reference, e.g. `ZAR`.", "example": "ZAR" }, { "name": "referenceCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The reference code returned when the reference was created.", "example": "VPAY-7K2Q9RT" } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND": { "summary": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND (-15114)", "value": { "code": -15114, "message": "Deposit reference not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_DELETE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_DELETE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ], "summary": "Delete a deposit reference", "description": "Deletes a deposit reference, so it no longer appears in your list or search results and can't be retrieved or updated. Deleted references don't count towards your maximum number of references.", "tags": [ "Deposit references" ] }, "put": { "operationId": "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the reference, e.g. `ZAR`.", "example": "ZAR" }, { "name": "referenceCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The reference code returned when the reference was created.", "example": "VPAY-7K2Q9RT" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingUniqueDepositReferenceRequest" }, "example": { "expectedAmount": "2000", "email": "thandi.nkosi@example.com" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueDepositReferenceForDisplay" }, "example": { "referenceCode": "VPAY-7K2Q9RT", "currency": "ZAR", "expectedAmount": "2000", "createdAt": 1792742400000, "name": "Thandi Nkosi", "email": "thandi.nkosi@example.com", "matchedDeposits": [], "matchedDepositCount": 1 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND": { "summary": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND (-15114)", "value": { "code": -15114, "message": "Deposit reference not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_UPDATE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_UPDATE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ], "summary": "Update a deposit reference", "description": "Updates the expected amount, payer name or payer email of a deposit reference; fields you leave out keep their current values. The response includes `matchedDepositCount` but not the matched deposits themselves.", "tags": [ "Deposit references" ] } }, "/v2/wallet/fiat/{currency}/payment/references": { "post": { "operationId": "postV2WalletFiatByCurrencyPaymentReferences", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the reference, e.g. `ZAR`.", "example": "ZAR" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingUniqueDepositReferenceRequest" }, "example": { "expectedAmount": "1500", "name": "Thandi Nkosi", "email": "thandi@example.com" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueDepositReferenceForDisplay" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED": { "summary": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED (-15116)", "value": { "code": -15116, "message": "Daily deposit reference generation limit exceeded" } }, "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED": { "summary": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED (-15119)", "value": { "code": -15119, "message": "Total deposit reference limit reached" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_CREATE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_CREATE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "code": -15116, "name": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Daily deposit reference generation limit exceeded", "reason": "You've reached the daily limit for creating references." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "code": -15119, "name": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Total deposit reference limit reached", "reason": "You've reached the maximum number of references." } ], "summary": "Create a deposit reference", "description": "Creates a unique deposit reference for a payer. Give the reference to the payer; deposits that quote it are matched to it. You can record the amount you expect and the payer's name and email to help you reconcile deposits.", "tags": [ "Deposit references" ] }, "get": { "operationId": "getV2WalletFiatByCurrencyPaymentReferences", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the references, e.g. `ZAR`.", "example": "ZAR" }, { "name": "matched", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` for references with at least one matched deposit, `false` for references with none. Leave it out to return both.", "example": true }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text: a full reference code for an exact match, or part of a payer's name or email for a fuzzy match. Shorter than two characters returns no results.", "example": "Thandi" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Same as `query`; used only when `query` isn't set.", "example": "Thandi" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Same as `query`; used only when neither `query` nor `name` is set.", "example": "thandi@example.com" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of references to return. Values above 1000 are treated as 1000.", "example": 100 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniqueDepositReferenceSearchResponse" }, "example": { "items": [ { "referenceCode": "VPAY-7K2Q9RT", "currency": "ZAR", "expectedAmount": "1500", "createdAt": 1792742400000, "name": "Thandi Nkosi", "email": "thandi@example.com", "matchedDeposits": [], "matchedDepositCount": 1 }, { "referenceCode": "VPAY-M4XH8WD", "currency": "ZAR", "createdAt": 1792571400000, "name": "Pieter van der Merwe", "email": "pieter@example.com", "matchedDeposits": [], "matchedDepositCount": 0 } ], "total": 2, "limit": 100, "offset": 0, "truncated": false } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`matched` isn't `true` or `false`, `skip` or `limit` isn't a whole number, `query`, `name` or `email` is empty or too long, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." } ], "summary": "List deposit references", "description": "Lists your deposit references in this currency, newest first, with the number of deposits matched to each; get a single reference to see the deposits themselves. Pass `query` to search by reference code, payer name or payer email instead, with the best matches first.", "tags": [ "Deposit references" ] } }, "/v1/account/balances": { "get": { "operationId": "getV1AccountBalances", "parameters": [ { "name": "excludeZeroBalances", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Leave out currencies with a zero balance." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1AccountBalanceWithTotalForDisplay" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "ACCOUNT_BALANCES_READ", "x-valr-bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "VALR_PAY_WRITE" ], "x-valr-permissions": [ { "name": "ACCOUNT_BALANCES_READ", "bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "VALR_PAY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true } ], "summary": "Get balances", "description": "Returns the balance of each currency in the account.", "tags": [ "Balances" ] } }, "/v2/payments/bulk-withdrawals/batches/{id}": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBatchesById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Batch ID.", "example": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ], "summary": "Get a disbursement batch", "description": "Returns a disbursement batch with its status and totals. While withdrawals in the batch are still pending, `feeQuote` shows the fees they will incur.", "tags": [ "Disbursements" ] } }, "/v1/webhooks": { "get": { "operationId": "getV1Webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionForDisplay" } }, "example": [ { "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90", "scopeKind": "ENTITY", "scopeLabel": "Entity", "url": "https://hooks.example.com/valr", "eventTypes": [ "FIAT_DEPOSIT_CREDITED", "FIAT_WITHDRAWAL_STATUS_UPDATE" ], "active": true, "description": "Treasury reconciliation", "signingSecretFingerprint": "7477002c", "createdAt": "2026-10-23T08:00:00.214367Z", "updatedAt": "2026-10-23T08:00:00.214367Z" }, { "identifier": "9a4c7e1f-2b6d-4f8a-8c3e-5d7b9f1a3c6e", "scopeKind": "ENTITY", "scopeLabel": "Entity", "url": "https://ops.example.com/hooks/crypto", "eventTypes": [ "CRYPTO_DEPOSIT_CREDITED", "SEND_STATUS_UPDATE" ], "active": false, "signingSecretFingerprint": "c19e04ab", "createdAt": "2026-10-01T13:42:07.581902Z", "updatedAt": "2026-10-20T09:05:44.017356Z" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_READ", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_READ", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true } ], "summary": "List webhooks", "description": "Returns your business's webhooks, newest first. Keys restricted to sub-accounts can't use this endpoint.", "tags": [ "Webhooks" ] }, "post": { "operationId": "postV1Webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingCreateWebhookSubscriptionRequest" }, "example": { "url": "https://hooks.example.com/valr", "eventTypes": [ "FIAT_DEPOSIT_CREDITED", "FIAT_WITHDRAWAL_STATUS_UPDATE" ], "description": "Treasury reconciliation" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreatedForDisplay" }, "example": { "subscription": { "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90", "scopeKind": "ENTITY", "scopeLabel": "Entity", "url": "https://hooks.example.com/valr", "eventTypes": [ "FIAT_DEPOSIT_CREDITED", "FIAT_WITHDRAWAL_STATUS_UPDATE" ], "active": true, "description": "Treasury reconciliation", "signingSecretFingerprint": "7477002c", "createdAt": "2026-10-23T08:00:00.214367Z", "updatedAt": "2026-10-23T08:00:00.214367Z" }, "signingSecret": "EXAMPLE-SIGNING-SECRET-do-not-use-000000000" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_LIMIT_REACHED": { "summary": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED (-18122)", "value": { "code": -18122, "message": "Webhook subscription limit reached:" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_MANAGE", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_MANAGE", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "code": -18122, "name": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "httpStatus": 400, "message": "Webhook subscription limit reached:", "reason": "Your business already has the maximum number of webhooks. Delete one you no longer need, then try again." } ], "summary": "Create a webhook", "description": "Creates a webhook that sends the chosen event types to your URL. The response includes the webhook's signing secret, which you need to verify deliveries: it's shown only once and can't be retrieved later, so store it securely. The URL must use HTTPS and resolve to a public IP address, and a key restricted to sub-accounts can't manage webhooks.", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteV1WebhooksById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID: the `identifier` returned when the webhook was created.", "example": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WEBHOOK_SUBSCRIPTION_NOT_FOUND (-18121)", "value": { "code": -18121, "message": "Webhook subscription not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_MANAGE", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_MANAGE", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID, or the `Content-Type: application/json` header is missing." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ], "summary": "Delete a webhook", "description": "Deletes a webhook so new events are no longer sent to it. Send a `Content-Type: application/json` header even though the request has no body. A key restricted to sub-accounts can't manage webhooks.", "tags": [ "Webhooks" ] }, "get": { "operationId": "getV1WebhooksById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID: the `identifier` returned when the webhook was created.", "example": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionForDisplay" }, "example": { "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90", "scopeKind": "ENTITY", "scopeLabel": "Entity", "url": "https://hooks.example.com/valr", "eventTypes": [ "FIAT_DEPOSIT_CREDITED", "FIAT_WITHDRAWAL_STATUS_UPDATE" ], "active": true, "description": "Treasury reconciliation", "signingSecretFingerprint": "7477002c", "createdAt": "2026-10-23T08:00:00.214367Z", "updatedAt": "2026-10-23T08:00:00.214367Z" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WEBHOOK_SUBSCRIPTION_NOT_FOUND (-18121)", "value": { "code": -18121, "message": "Webhook subscription not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_READ", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_READ", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ], "summary": "Get a webhook", "description": "Returns a webhook. The signing secret isn't included; to check which secret it uses, compare `signingSecretFingerprint` with the first 8 hex characters of the SHA-256 hash of the secret you stored. Keys restricted to sub-accounts can't use this endpoint.", "tags": [ "Webhooks" ] }, "put": { "operationId": "putV1WebhooksById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID: the `identifier` returned when the webhook was created.", "example": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingUpdateWebhookSubscriptionRequest" }, "example": { "eventTypes": [ "FIAT_DEPOSIT_CREDITED", "CRYPTO_DEPOSIT_CREDITED" ], "description": "Deposits only" } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WEBHOOK_SUBSCRIPTION_NOT_FOUND (-18121)", "value": { "code": -18121, "message": "Webhook subscription not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_MANAGE", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_MANAGE", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ], "summary": "Update a webhook", "description": "Changes a webhook's URL, event types, description or active state; fields you leave out keep their current values, and the signing secret doesn't change. Set `active` to `false` to pause deliveries without deleting the webhook. A key restricted to sub-accounts can't manage webhooks.", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "getV1WebhooksByIdDeliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID: the `identifier` returned when the webhook was created.", "example": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of attempts to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of attempts to return, up to 100.", "example": 100 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveriesPageForDisplay" }, "example": { "items": [ { "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c", "eventType": "FIAT_DEPOSIT_CREDITED", "attemptNumber": 2, "responseStatus": 200, "terminalState": "SUCCESS", "createdAt": "2026-10-23T08:16:04.108392Z" }, { "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c", "eventType": "FIAT_DEPOSIT_CREDITED", "attemptNumber": 1, "errorCategory": "TIMEOUT", "errorMessage": "Your endpoint did not respond within the delivery timeout.", "nextRetryAt": "2026-10-23T08:16:03.512874Z", "createdAt": "2026-10-23T08:15:33.512874Z" } ], "total": 2, "limit": 100, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WEBHOOK_SUBSCRIPTION_NOT_FOUND (-18121)", "value": { "code": -18121, "message": "Webhook subscription not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_READ", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_READ", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID, `skip` or `limit` isn't an integer, or `limit` is more than 100." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ], "summary": "List webhook delivery attempts", "description": "Returns the attempts to deliver events to a webhook, newest first, with the total across all pages. A failed attempt explains why in `errorCategory` and `errorMessage`, and shows when it will be retried in `nextRetryAt`. Keys restricted to sub-accounts can't use this endpoint.", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/events/{eventId}": { "get": { "operationId": "getV1WebhooksByIdEventsByEventId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID: the `identifier` returned when the webhook was created.", "example": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90" }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Event ID: the `eventId` of a delivery attempt, or the `Valr-Webhook-Event-Id` header of a delivery.", "example": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventForDisplay" }, "example": { "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c", "eventType": "FIAT_DEPOSIT_CREDITED", "payload": "{\"id\":\"6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c\",\"type\":\"FIAT_DEPOSIT_CREDITED\",\"createdAt\":1792743330123,\"apiVersion\":\"2026-09-16\",\"subAccount\":null,\"data\":{\"depositId\":\"3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b\",\"amount\":\"1500\",\"currencySymbol\":\"ZAR\",\"reference\":\"VLR4F7K2Q9\",\"effectiveDate\":1792713600000,\"creditedAt\":1792743330000}}", "attempts": [ { "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c", "eventType": "FIAT_DEPOSIT_CREDITED", "attemptNumber": 1, "errorCategory": "TIMEOUT", "errorMessage": "Your endpoint did not respond within the delivery timeout.", "nextRetryAt": "2026-10-23T08:16:03.512874Z", "createdAt": "2026-10-23T08:15:33.512874Z" }, { "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c", "eventType": "FIAT_DEPOSIT_CREDITED", "attemptNumber": 2, "responseStatus": 200, "terminalState": "SUCCESS", "createdAt": "2026-10-23T08:16:04.108392Z" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WEBHOOK_SUBSCRIPTION_NOT_FOUND (-18121)", "value": { "code": -18121, "message": "Webhook subscription not found" } }, "ApplicationErrorCodes.WEBHOOK_EVENT_NOT_FOUND": { "summary": "WEBHOOK_EVENT_NOT_FOUND (-18123)", "value": { "code": -18123, "message": "Webhook event not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_READ", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_READ", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID or event ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." }, { "ref": "ApplicationErrorCodes.WEBHOOK_EVENT_NOT_FOUND", "code": -18123, "name": "WEBHOOK_EVENT_NOT_FOUND", "httpStatus": 404, "message": "Webhook event not found", "reason": "This webhook hasn't sent an event with this ID." } ], "summary": "Get a webhook event", "description": "Returns one event sent to a webhook: the exact JSON body that was delivered, as a string, and every attempt to deliver it, oldest first. Keys restricted to sub-accounts can't use this endpoint.", "tags": [ "Webhooks" ] } }, "/v1/webhooks/event-types": { "get": { "operationId": "getV1WebhooksEventTypes", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypeForDisplay" } }, "example": [ { "name": "NEW_PENDING_RECEIVE", "displayName": "Crypto deposit received", "description": "A crypto deposit was seen on-chain and is pending confirmation." }, { "name": "CRYPTO_DEPOSIT_CREDITED", "displayName": "Crypto deposit credited", "description": "A crypto deposit has been fully confirmed and credited to your balance." }, { "name": "FIAT_WITHDRAWAL_STATUS_UPDATE", "displayName": "Fiat withdrawal status", "description": "A fiat withdrawal changed status." }, { "name": "FIAT_DEPOSIT_CREDITED", "displayName": "Fiat deposit credited", "description": "A fiat bank deposit was credited to your account." } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WEBHOOKS_READ", "x-valr-bundles": [ "WEBHOOKS_WRITE" ], "x-valr-permissions": [ { "name": "WEBHOOKS_READ", "bundles": [ "WEBHOOKS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true } ], "summary": "List webhook event types", "description": "Lists the event types a webhook can subscribe to. Use the `name` values in `eventTypes` when you create or update a webhook.", "tags": [ "Webhooks" ] } }, "/v2/wallet/fiat/{currency}/payment/bulk-references": { "post": { "operationId": "postV2WalletFiatByCurrencyPaymentBulkReferences", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the references, e.g. `ZAR`.", "example": "ZAR" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDepositReferenceRequest" }, "example": { "senders": [ { "name": "Thandi Nkosi", "email": "thandi@example.com", "expectedAmount": "1500" }, { "name": "Pieter van der Merwe", "email": "pieter@example.com" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDepositJobResponse" }, "example": { "jobId": 4182, "totalItems": 2, "acceptedItems": 2 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE": { "summary": "BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE (-15121)", "value": { "code": -15121, "message": "Batch size exceeds maximum allowed" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } }, "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_INVALID_SENDER": { "summary": "BULK_DEPOSIT_REFERENCE_INVALID_SENDER (-15123)", "value": { "code": -15123, "message": "Invalid sender information" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS": { "summary": "BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS (-15124)", "value": { "code": -15124, "message": "A bulk deposit job is already being processed" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED": { "summary": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED (-15119)", "value": { "code": -15119, "message": "Total deposit reference limit reached" } }, "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED": { "summary": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED (-15116)", "value": { "code": -15116, "message": "Daily deposit reference generation limit exceeded" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED": { "summary": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED (-15120)", "value": { "code": -15120, "message": "Bulk deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_CREATE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_CREATE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "code": -15121, "name": "BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "httpStatus": 400, "message": "Batch size exceeds maximum allowed", "reason": "`senders` has more payers than a single batch allows. Split them into smaller batches." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "code": -15124, "name": "BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "httpStatus": 409, "message": "A bulk deposit job is already being processed", "reason": "An earlier bulk job is still processing. Wait for it to finish, then try again." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "code": -15123, "name": "BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "httpStatus": 400, "message": "Invalid sender information", "reason": "An entry in `senders` is `null`, a payer's name or email is missing or invalid, or their expected amount isn't a number greater than zero; the message identifies up to three such payers by their position in `senders`, and no job is created." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "code": -15119, "name": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Total deposit reference limit reached", "reason": "The batch would take you past the maximum number of references. Delete references you no longer need or submit fewer payers." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "code": -15116, "name": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Daily deposit reference generation limit exceeded", "reason": "The batch would take you past the daily limit for creating references. Submit fewer payers or try again tomorrow." } ], "summary": "Create deposit references in bulk", "description": "Starts a background job that creates a deposit reference for each payer in `senders` and returns its `jobId`; if any payer is invalid or the batch would take you past your reference limits, the whole batch is rejected. Poll Get a bulk reference job until `status` is no longer `PROCESSING`, then list the job's items to get each payer's reference code.", "tags": [ "Deposit references" ] } }, "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}": { "get": { "operationId": "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the references, e.g. `ZAR`.", "example": "ZAR" }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The `jobId` returned when the bulk job was created.", "example": 4182 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDepositJobStatusResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND": { "summary": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND (-15122)", "value": { "code": -15122, "message": "Bulk deposit job not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED": { "summary": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED (-15120)", "value": { "code": -15120, "message": "Bulk deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The job ID isn't a whole number, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "code": -15122, "name": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "httpStatus": 404, "message": "Bulk deposit job not found", "reason": "No bulk job with this ID exists on your account for this currency." } ], "summary": "Get a bulk reference job", "description": "Returns the status of a bulk reference job. `completedItems` and `failedItems` are filled in when the job finishes; while it's `PROCESSING`, list the job's items to follow its progress.", "tags": [ "Deposit references" ] } }, "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items": { "get": { "operationId": "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the references, e.g. `ZAR`.", "example": "ZAR" }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The `jobId` returned when the bulk job was created.", "example": 4182 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED" ] }, "description": "Only return items with this status. Case-insensitive.", "example": "FAILED" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of items to return, between 1 and 1000; values outside that range are clamped.", "example": 100 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDepositItemsResponse" }, "example": { "items": [ { "senderIndex": 0, "currency": "ZAR", "expectedAmount": "1500", "name": "Thandi Nkosi", "email": "thandi@example.com", "status": "SUCCESS", "referenceCode": "VPAY-7K2Q9RT", "processedAt": 1792749605000 }, { "senderIndex": 1, "currency": "ZAR", "name": "Pieter van der Merwe", "email": "pieter@example.com", "status": "FAILED", "errorCode": -15116, "processedAt": 1792749606000 } ], "total": 2, "limit": 100, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND": { "summary": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND (-15122)", "value": { "code": -15122, "message": "Bulk deposit job not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED": { "summary": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED (-15120)", "value": { "code": -15120, "message": "Bulk deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The job ID, `skip` or `limit` isn't a whole number, `status` isn't `PENDING`, `SUCCESS` or `FAILED`, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "code": -15122, "name": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "httpStatus": 404, "message": "Bulk deposit job not found", "reason": "No bulk job with this ID exists on your account for this currency." } ], "summary": "List bulk reference job items", "description": "Lists the payers in a bulk reference job in the order they were submitted, with the reference created for each or, if creation failed, an `errorCode`. Filter by `status` to fetch only the references that were created, that failed or that are still pending.", "tags": [ "Deposit references" ] } }, "/v2/wallet/fiat/{currency}/payment/deposits": { "get": { "operationId": "getV2WalletFiatByCurrencyPaymentDeposits", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the deposits, e.g. `ZAR`.", "example": "ZAR" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Maximum number of deposits to return. Values above 1000 are treated as 1000.", "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFiatDepositsSearchResponse" }, "example": { "items": [ { "publicId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "amount": "1500", "effectiveDate": "2026-10-23", "creditedAt": 1792746900000, "linkedReferenceCode": "VPAY-7K2Q9RT" }, { "publicId": "9a7b6c5d-4e3f-4a2b-8c1d-0e9f8a7b6c5d", "amount": "820.5", "effectiveDate": "2026-10-22", "creditedAt": 1792675200000 } ], "total": 2, "limit": 20, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED": { "summary": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED (-15117)", "value": { "code": -15117, "message": "Unique deposit references are not available at this time" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." } ], "summary": "List credited deposits", "description": "Lists the deposits credited to your collections account in this currency, newest first, with the reference each one is linked to. Use it to find a deposit's `publicId` when you want to link it to a different reference.", "tags": [ "Deposit references" ] } }, "/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference": { "delete": { "operationId": "deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the deposits, e.g. `ZAR`.", "example": "ZAR" }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The deposit's `publicId`.", "example": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b" } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND": { "summary": "FIAT_DEPOSIT_NOT_FOUND (-15118)", "value": { "code": -15118, "message": "Deposit not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_DELETE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_DELETE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The deposit ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND", "code": -15118, "name": "FIAT_DEPOSIT_NOT_FOUND", "httpStatus": 404, "message": "Deposit not found", "reason": "No deposit with this ID exists on your collections account." } ], "summary": "Unlink a deposit from its reference", "description": "Removes the link between a deposit and its reference. The deposit stays credited, but no longer counts as a matched deposit for any reference.", "tags": [ "Deposit references" ] }, "put": { "operationId": "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the deposits, e.g. `ZAR`.", "example": "ZAR" }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The deposit's `publicId`.", "example": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingDepositReferenceLinkRequest" }, "example": { "referenceCode": "VPAY-7K2Q9RT" } } } }, "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE": { "summary": "UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE (-15115)", "value": { "code": -15115, "message": "Deposit override is invalid" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND": { "summary": "FIAT_DEPOSIT_NOT_FOUND (-15118)", "value": { "code": -15118, "message": "Deposit not found" } }, "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND": { "summary": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND (-15114)", "value": { "code": -15114, "message": "Deposit reference not found" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_UPDATE", "x-valr-bundles": [ "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_UPDATE", "bundles": [ "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND", "code": -15118, "name": "FIAT_DEPOSIT_NOT_FOUND", "httpStatus": 404, "message": "Deposit not found", "reason": "No deposit with this ID exists on your collections account." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "code": -15115, "name": "UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "httpStatus": 400, "message": "Deposit override is invalid", "reason": "The deposit hasn't been fully credited yet." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ], "summary": "Link a deposit to a reference", "description": "Links a credited deposit to one of your deposit references, replacing any reference it was already matched to. Use it to correct which payer a deposit is attributed to; the funds stay where they are.", "tags": [ "Deposit references" ] } }, "/v2/payments": { "get": { "operationId": "getV2Payments", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of payments to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of payments to skip, for paging.", "example": 0 }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`COLLECTION` for payments from payers, `DISBURSEMENT` for deposits that fund disbursements.", "example": "COLLECTION" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Settlement status: `PENDING`, `SETTLED` or `FAILED`.", "example": "SETTLED" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only include payments received at or after this time, in Unix milliseconds.", "example": 1792627200000 }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only include payments received before this time, in Unix milliseconds.", "example": 1792713600000 }, { "name": "minAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Smallest deposit amount to include, as a decimal string.", "example": "100.00" }, { "name": "maxAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Largest deposit amount to include, as a decimal string.", "example": "5000.00" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include payments with this currency on any leg: deposit, conversion or payout.", "example": "ZAR" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Payer reference, or part of one. Not case-sensitive.", "example": "VLR4F7K2" }, { "name": "referenceCodes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated payer references. Only payments with one of these exact references are included.", "example": "VLR4F7K2Q9,VLR8M3N6P1" }, { "name": "payer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Same as `referenceCodes`; ignored when `referenceCodes` is sent.", "example": "VLR4F7K2Q9" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches an exact amount on any leg, and anything else matches a currency or payer reference. Explicit filters take precedence.", "example": "2026-10-22" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`.", "example": "Africa/Johannesburg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" }, "example": { "items": [ { "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "status": "COMPLETED", "mode": "SCHEDULED", "type": "COLLECTION", "inflowCurrency": "ZAR", "inflowAmount": "1500.00", "convertedCurrency": "USDC", "convertedAmount": "82.45", "outflowCurrency": "USDC", "outflowAmount": "82.45", "receivedAt": 1792660500000, "settlementAt": 1792684950000, "settlementStatus": "SETTLED", "settlementRef": null, "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "linked": true, "payerName": "Thandi Nkosi", "reference": "VLR4F7K2Q9", "timeline": null, "payouts": null } ], "total": 1, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List payments", "description": "Returns payments received across every account in your business, newest first: each deposit, from a payer or to fund disbursements, with its conversion and settlement. Filter by type, settlement status, date, amount, currency or payer reference.", "tags": [ "Getting paid" ] } }, "/v2/payments/{id}": { "get": { "operationId": "getV2PaymentsById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment ID.", "example": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentForUser" }, "example": { "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "status": "COMPLETED", "mode": "SCHEDULED", "type": "COLLECTION", "inflowCurrency": "ZAR", "inflowAmount": "1500.00", "convertedCurrency": "USDC", "convertedAmount": "82.45", "outflowCurrency": "USDC", "outflowAmount": "82.45", "receivedAt": 1792660500000, "settlementAt": 1792684950000, "settlementStatus": "SETTLED", "settlementRef": null, "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "linked": true, "payerName": "Thandi Nkosi", "reference": "VLR4F7K2Q9", "timeline": [ { "type": "FUNDING", "label": "1500.00 ZAR collected", "status": "COMPLETE", "data": { "currency": "ZAR", "amount": "1500.00" }, "traceId": null, "at": 1792660500000 }, { "type": "CONVERSION", "label": "Converted to 82.45 USDC", "status": "COMPLETE", "data": { "fromCurrency": "ZAR", "fromAmount": "1500.00", "toCurrency": "USDC", "toAmount": "82.45", "rate": "18.1928", "conversionId": "b7d9f1a3-5c2e-4b8d-a6f0-3e5c7a9b1d4f" }, "traceId": "b7d9f1a3-5c2e-4b8d-a6f0-3e5c7a9b1d4f", "at": 1792660565000 }, { "type": "SWEEP", "label": "Swept to payout account", "status": "COMPLETE", "data": { "currency": "USDC", "amount": "82.45" }, "traceId": null, "at": 1792660600000 }, { "type": "SETTLEMENT", "label": "Settled", "status": "COMPLETE", "data": { "currency": "USDC", "amount": "82.45" }, "traceId": null, "at": 1792684950000 } ], "payouts": [ { "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "amount": "82.45", "currency": "USDC", "status": "SETTLED", "settledAt": 1792684950000 } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The payment ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payment with this ID exists in your business." } ], "summary": "Get a payment", "description": "Returns a payment with its step-by-step timeline and the settled payouts that carried it. The payment can be on any account in your business.", "tags": [ "Getting paid" ] } }, "/v2/payments/collect/events": { "get": { "operationId": "getV2PaymentsCollectEvents", "parameters": [ { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`.", "example": "USDC" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of payments to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of payments to skip, for paging.", "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageScheduledWithdrawalEventForUser" }, "example": { "items": [ { "id": "6b0d2f4a-8c1e-4a3b-9d5f-7e9a1b3c5d7e", "withdrawalCurrency": "USDC", "withdrawalAmount": "54.20", "receivedAt": 1792744300000, "status": "SCHEDULED", "depositCurrency": "ZAR", "depositAmount": "985.00", "payerName": "Sipho Dlamini", "reference": "VLR8M3N6P1", "timeline": null } ], "total": 1, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List queued scheduled payments", "description": "Returns payments waiting for their next scheduled payout run, newest first, across every payout schedule in your business.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/events/{id}": { "get": { "operationId": "getV2PaymentsCollectEventsById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Scheduled payment ID, from List queued scheduled payments or List processed scheduled payments.", "example": "6b0d2f4a-8c1e-4a3b-9d5f-7e9a1b3c5d7e" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledWithdrawalEventForUser" }, "example": { "id": "6b0d2f4a-8c1e-4a3b-9d5f-7e9a1b3c5d7e", "withdrawalCurrency": "USDC", "withdrawalAmount": "54.20", "receivedAt": 1792744300000, "status": "SCHEDULED", "depositCurrency": "ZAR", "depositAmount": "985.00", "payerName": "Sipho Dlamini", "reference": "VLR8M3N6P1", "timeline": [ { "type": "CONVERSION", "label": "Converted to 54.20 USDC", "status": "COMPLETE", "data": { "fromCurrency": "ZAR", "fromAmount": "985.00", "toCurrency": "USDC", "toAmount": "54.20", "rate": "18.1734", "conversionId": "d1f3b5a7-9e2c-4d6f-8a0b-5c7e9f1a3b6d" }, "traceId": "d1f3b5a7-9e2c-4d6f-8a0b-5c7e9f1a3b6d", "at": 1792744270000 }, { "type": "SETTLEMENT", "label": "Settlement pending", "status": "PENDING", "data": { "currency": "USDC", "amount": "54.20", "scheduledFor": "2026-10-23T16:00:00Z" }, "traceId": null, "at": 1792771200000 } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The scheduled payment ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No scheduled payment with this ID exists on your business's payout schedules." } ], "summary": "Get a scheduled payment", "description": "Returns one payment on a payout schedule, with the deposit it came from and its timeline. It must be on one of your business's payout schedules.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/history": { "get": { "operationId": "getV2PaymentsCollectHistory", "parameters": [ { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`.", "example": "USDC" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of payments to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of payments to skip, for paging.", "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageScheduledWithdrawalEventForUser" }, "example": { "items": [ { "id": "2e4a6c8b-0d1f-4a3c-9e5b-7d9f1b3a5c7e", "withdrawalCurrency": "USDC", "withdrawalAmount": "82.45", "receivedAt": 1792660600000, "status": "COMPLETED", "depositCurrency": "ZAR", "depositAmount": "1500.00", "payerName": "Thandi Nkosi", "reference": "VLR4F7K2Q9", "timeline": null } ], "total": 1, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List processed scheduled payments", "description": "Returns payments that scheduled payout runs have picked up (processing, completed or failed), newest first, across every payout schedule in your business.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/runs/{id}": { "get": { "operationId": "getV2PaymentsCollectRunsById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payout run ID.", "example": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalRunForDisplay" }, "example": { "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "scheduledFor": 1792684800000, "cutoffAt": 1792677600000, "status": "DONE", "totalAmount": "1240.75", "currency": "USDC", "createdAt": 1792598405000 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The run ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payout run with this ID exists on your business's payout schedules." } ], "summary": "Get a payout run", "description": "Returns one scheduled payout run with its timing, status and total. The run must belong to one of your business's payout schedules.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/runs/{id}/payments": { "get": { "operationId": "getV2PaymentsCollectRunsByIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payout run ID.", "example": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of payments to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of payments to skip, for paging.", "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" }, "example": { "items": [ { "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "status": "COMPLETED", "mode": "SCHEDULED", "type": "COLLECTION", "inflowCurrency": "ZAR", "inflowAmount": "1500.00", "convertedCurrency": "USDC", "convertedAmount": "82.45", "outflowCurrency": "USDC", "outflowAmount": "82.45", "receivedAt": 1792660500000, "settlementAt": 1792684950000, "settlementStatus": "SETTLED", "settlementRef": null, "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "linked": true, "payerName": "Thandi Nkosi", "reference": "VLR4F7K2Q9", "timeline": null, "payouts": null } ], "total": 23, "limit": 1, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The run ID isn't a valid UUID." } ], "summary": "List a payout run's payments", "description": "Returns the payments a scheduled payout run includes. An ID that isn't one of your business's runs returns an empty page.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/runs/history": { "get": { "operationId": "getV2PaymentsCollectRunsHistory", "parameters": [ { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include runs that pay out in this currency. Use the upper-case code, e.g. `USDC`.", "example": "USDC" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of runs to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of runs to skip, for paging.", "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageWithdrawalRunForDisplay" }, "example": { "items": [ { "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "scheduledFor": 1792684800000, "cutoffAt": 1792677600000, "status": "DONE", "totalAmount": "1240.75", "currency": "USDC", "createdAt": 1792598405000 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List payout runs", "description": "Returns scheduled payout runs, latest scheduled time first, across every payout schedule in your business.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/schedules": { "get": { "operationId": "getV2PaymentsCollectSchedules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalScheduleForDisplay" } }, "example": [ { "id": "1a7c3e5b-9d2f-4b6a-8e0c-2f4a6b8d0e1c", "currency": "USDC", "kind": "CRYPTO", "intervalType": "DAILY", "timeOfDay": "18:00", "zoneId": "Africa/Johannesburg", "dayOfWeek": null, "cutoffMinutes": 120, "paymentInstrumentId": "e2a4c6b8-0d1f-4e3a-b5c7-9d1e3f5a7b9c", "isActive": true, "createdAt": 1790848800000, "updatedAt": 1792067400000 } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List payout schedules", "description": "Returns every payout schedule set up for your business, including inactive ones. Schedules are managed by VALR.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collect/settlements": { "get": { "operationId": "getV2PaymentsCollectSettlements", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of settlements to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of settlements to skip, for paging.", "example": 0 }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`COLLECTION` or `DISBURSEMENT`: only include settlements of that type of payment.", "example": "COLLECTION" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`PENDING`, `SETTLED`, `FAILED` or `PARTIALLY_SETTLED`.", "example": "SETTLED" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only count payments received at or after this time, in Unix milliseconds.", "example": 1792627200000 }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only count payments received before this time, in Unix milliseconds.", "example": 1792713600000 }, { "name": "minAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Smallest settlement total to include, as a decimal string.", "example": "100.00" }, { "name": "maxAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Largest settlement total to include, as a decimal string.", "example": "50000.00" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Payout currency.", "example": "USDC" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches a settlement total exactly, and anything else matches the payout currency. Explicit filters take precedence.", "example": "2026-10-22" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`.", "example": "Africa/Johannesburg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSettlementForUser" }, "example": { "items": [ { "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "currency": "USDC", "totalAmount": "1240.75", "settledAmount": "1240.75", "paymentCount": 23, "status": "SETTLED", "settledAt": 1792684950000, "receivedAt": 1792676400000 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List settlements", "description": "Returns settlements across every account in your business: each is a scheduled payout run or an instant payout of collected funds. Unsettled ones come first, then the most recently settled.", "tags": [ "Settlements" ] } }, "/v2/payments/collect/settlements/{id}": { "get": { "operationId": "getV2PaymentsCollectSettlementsById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "Settlement ID: a payout run ID for a scheduled payout, or a payout ID for an instant payout.", "example": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementForUser" }, "example": { "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "currency": "USDC", "totalAmount": "1240.75", "settledAmount": "1240.75", "paymentCount": 23, "status": "SETTLED", "settledAt": 1792684950000, "receivedAt": 1792676400000 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement with this ID exists in your business." } ], "summary": "Get a settlement", "description": "Returns one settlement with its totals and status. The settlement must belong to your business.", "tags": [ "Settlements" ] } }, "/v2/payments/collect/settlements/{id}/payments": { "get": { "operationId": "getV2PaymentsCollectSettlementsByIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "Settlement ID.", "example": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of payments to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of payments to skip, for paging.", "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" }, "example": { "items": [ { "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b", "status": "COMPLETED", "mode": "SCHEDULED", "type": "COLLECTION", "inflowCurrency": "ZAR", "inflowAmount": "1500.00", "convertedCurrency": "USDC", "convertedAmount": "82.45", "outflowCurrency": "USDC", "outflowAmount": "82.45", "receivedAt": 1792660500000, "settlementAt": 1792684950000, "settlementStatus": "SETTLED", "settlementRef": null, "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "linked": true, "payerName": "Thandi Nkosi", "reference": "VLR4F7K2Q9", "timeline": null, "payouts": null } ], "total": 23, "limit": 1, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement with this ID exists in your business." } ], "summary": "List a settlement's payments", "description": "Returns the payments a settlement paid out, newest first. The settlement must belong to your business.", "tags": [ "Settlements" ] } }, "/v2/payments/collect/settlements/wallet": { "get": { "operationId": "getV2PaymentsCollectSettlementsWallet", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWalletForUser" }, "example": { "id": "e2a4c6b8-0d1f-4e3a-b5c7-9d1e3f5a7b9c", "name": "Treasury USDC", "address": "0x7a2D4c9E1b3F5a8C0d6E2f4B9c1A3e5D7b9F0c2E", "network": "Ethereum", "currency": "USDC", "beneficiaryName": "Acme Trading (Pty) Ltd", "serviceProviderName": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement wallet is set up for your business." } ], "summary": "Get the settlement wallet", "description": "Returns the crypto wallet your business's collected funds settle to.", "tags": [ "Settlements" ] } }, "/v2/payments/collect/upcoming": { "get": { "operationId": "getV2PaymentsCollectUpcoming", "parameters": [ { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`.", "example": "USDC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UpcomingWithdrawalForUser" } }, "example": [ { "scheduleId": "1a7c3e5b-9d2f-4b6a-8e0c-2f4a6b8d0e1c", "currency": "USDC", "nextRunAt": 1792771200000, "cutoffAt": 1792764000000, "totalAmount": "54.20", "eventCount": 1 } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "Get upcoming scheduled payouts", "description": "Returns one entry per active payout schedule in your business, with the next run time, its cut-off and the total queued so far. A schedule with nothing queued shows a zero total and no run times.", "tags": [ "Collection schedules" ] } }, "/v2/payments/collections/history": { "get": { "operationId": "getV2PaymentsCollectionsHistory", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of entries to return.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of entries to skip, for paging.", "example": 0 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Settlement status of payments: `PENDING`, `SETTLED` or `FAILED`.", "example": "SETTLED" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only include entries received at or after this time, in Unix milliseconds.", "example": 1792627200000 }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only include entries received before this time, in Unix milliseconds.", "example": 1792713600000 }, { "name": "minAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Smallest payment amount to include, as a decimal string.", "example": "100.00" }, { "name": "maxAmount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Largest payment amount to include, as a decimal string.", "example": "5000.00" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include payments with this currency on any leg: deposit, conversion or payout.", "example": "ZAR" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Payer reference, or part of one. Not case-sensitive.", "example": "VLR4F7K2" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches an exact amount, and anything else matches a currency or payer reference. Explicit filters take precedence.", "example": "2026-10-22" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`.", "example": "Africa/Johannesburg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCollectionActivityForUser" }, "example": { "items": [ { "kind": "SETTLEMENT", "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f", "date": 1792684950000, "status": "SETTLED", "amount": "1240.75", "currency": "USDC", "convertedAmount": null, "convertedCurrency": null, "from": "Collections", "to": "USDC Wallet", "reference": "Settlement", "paymentId": null, "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" }, { "kind": "PAYMENT", "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "date": 1792660500000, "status": "COMPLETED", "amount": "1500.00", "currency": "ZAR", "convertedAmount": "82.45", "convertedCurrency": "USDC", "from": "Thandi Nkosi", "to": "Collections", "reference": "VLR4F7K2Q9", "paymentId": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f", "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "COLLECTIONS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ], "x-valr-permissions": [ { "name": "COLLECTIONS_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List collection activity", "description": "Returns one feed of payments received from payers and completed settlements of collected funds, newest first, across every account in your business. A `status` other than `SETTLED` leaves settlements out.", "tags": [ "Getting paid" ] } }, "/v2/payments/account/balances/{type}": { "get": { "operationId": "getV2PaymentsAccountBalancesByType", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "PAYOUT", "COLLECTIONS", "FUNDING", "HOLD" ] }, "description": "Which payments account to read: `PAYOUT` (pays your disbursements), `COLLECTIONS` (receives collections), `FUNDING` (receives the deposits that fund your payouts) or `HOLD` (holds collected funds until you convert or withdraw them). Case-insensitive.", "example": "PAYOUT" }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Currency of the account to read, e.g. `ZAR`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceResponse" } }, "example": [ { "currency": { "shortName": "ZAR", "symbol": "R", "longName": "Rand" }, "available": "125000.00", "reserved": "0", "total": "125000.00" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "PAYMENTS_BALANCES_READ", "x-valr-bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "PAYMENTS_BALANCES_READ", "bundles": [ "PAYMENTS_READ", "COLLECTIONS_WRITE", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`type` isn't one of `PAYOUT`, `COLLECTIONS`, `FUNDING` or `HOLD`." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "Your business has no account of this type set up for `currency`." } ], "summary": "Get payments account balances", "description": "Returns the balances of one of your business's payments accounts, chosen by account type and currency. The response lists every currency held in that account.", "tags": [ "Payments balances" ] } }, "/v2/payments/bulk-withdrawals/banks": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBanks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankDefinition" } }, "example": [ { "code": "ABSA", "displayName": "ABSA Bank", "defaultBranchCode": "632005", "rtcParticipant": true }, { "code": "CAPITEC", "displayName": "Capitec Bank", "defaultBranchCode": "470010", "rtcParticipant": false }, { "code": "FNB", "displayName": "FNB/RMB", "defaultBranchCode": "250655", "rtcParticipant": true } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List supported banks", "description": "Returns the banks you can pay out to, with each bank's default branch code. Send a bank's `code` as `bank` when you create withdrawals or beneficiaries.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/batches": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBatches", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING_APPROVAL", "APPROVED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ] }, "description": "Only batches with this status.", "example": "PROCESSING" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Page size, from 1 to 200; values outside that range are clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedBulkWithdrawalBatchForDisplay" }, "example": { "items": [ { "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d", "label": "October salaries", "currency": "ZAR", "totalAmount": "20501.00", "withdrawalCount": 2, "status": "COMPLETED", "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "uploadedByName": null, "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "approvedByName": null, "approvedAt": "2026-10-23T08:15:02.481Z", "createdAt": "2026-10-23T08:15:01.912Z", "updatedAt": "2026-10-23T09:02:44.118Z", "completedAt": "2026-10-23T09:02:44.118Z", "feeQuote": null } ], "total": 1, "limit": 50, "offset": 0, "truncated": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List disbursement batches", "description": "Returns your disbursement batches, newest first, a page at a time.", "tags": [ "Disbursements" ] }, "post": { "operationId": "postV2PaymentsBulkWithdrawalsBatches", "parameters": [ { "name": "X-VALR-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.\\-]{1,128}$", "maxLength": 128 }, "description": "Your unique key for this batch: up to 128 letters, digits, `:`, `_`, `.` or `-`. Reuse it only to retry the same request.", "example": "payroll-2026-10-23-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalCreateBulkWithdrawalBatchRequest" }, "example": { "label": "October salaries", "withdrawals": [ { "bank": "FNB", "accountHolder": "Thandi Nkosi", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "amount": 12500.75, "reference": "OCT SALARY", "email": "thandi@example.com", "type": "INDIVIDUAL", "country": "ZA" }, { "bank": "CAPITEC", "accountHolder": "Sipho Dlamini", "accountNumber": "1453987621", "branchCode": "470010", "accountType": "SAVINGS", "amount": 8000.25, "reference": "OCT SALARY" } ] } } } }, "responses": { "200": { "description": "A batch with this idempotency key already exists. Its ID is returned and nothing new is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalCreateBulkWithdrawalBatchResponse" }, "example": { "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d" } } } }, "202": { "description": "Batch created and executed. Check its progress with `GET /v2/payments/bulk-withdrawals/batches/{id}`; individual payouts can still fail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalCreateBulkWithdrawalBatchResponse" }, "example": { "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.CONFLICT": { "summary": "CONFLICT (CONFLICT)", "value": { "code": "CONFLICT", "message": "Resource conflict." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_CREATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_CREATE", "bundles": [ "DISBURSEMENTS_WRITE" ] }, { "name": "DISBURSEMENTS_APPROVE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or has no `withdrawals` array, or `X-VALR-Idempotency-Key` isn't valid, in which case `validationErrors` names the header." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "The idempotency key belongs to a batch that was cancelled, so retry with a new key, or to one that failed after its fee was charged, so contact support instead of retrying." } ], "summary": "Create a disbursement batch", "description": "Creates a batch of ZAR payouts and executes it straight away: batches created with an API key skip the approval step, so the fee is charged and the payouts are submitted immediately, and the key needs the `DISBURSEMENTS_APPROVE` permission as well (the `DISBURSEMENTS_WRITE` bundle includes it). Your payout account must have enough available balance for the payouts plus the fee. `X-VALR-Idempotency-Key` is optional. Send one to make retries safe: repeating a key returns the original batch's ID with status 200. Without it, every request creates a new batch.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/batches/{id}/cancel": { "post": { "operationId": "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Batch ID.", "example": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" }, "example": { "id": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f", "label": "November rent", "currency": "ZAR", "totalAmount": "45000.00", "withdrawalCount": 3, "status": "CANCELLED", "uploadedBy": "2e4a6c8e-0b1d-4f3a-9c5e-7a9b1d3f5a7c", "uploadedByName": { "name": "Lerato", "surname": "Mokoena" }, "approvedBy": null, "approvedByName": null, "approvedAt": null, "createdAt": "2026-10-22T14:03:11.250Z", "updatedAt": "2026-10-23T08:40:27.733Z", "completedAt": null, "feeQuote": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_UPDATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_UPDATE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ], "summary": "Cancel a disbursement batch", "description": "Cancels a batch that is pending approval or approved, and marks its withdrawals that haven't been submitted as `SKIPPED`. Batches created with an API key are executed immediately, so they usually can't be cancelled.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/batches/{id}/fee-quote": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Batch ID.", "example": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" }, "example": { "fee": "25.00", "currency": "ZAR", "withdrawalCount": 2, "grossTotal": "20501.00", "requiredTotal": "20526.00", "feeGroups": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ], "summary": "Get a batch's fee quote", "description": "Returns the fee for the batch's withdrawals that are still pending or, once none are pending, the fee that was charged. Unlike `GET /v2/payments/bulk-withdrawals/batches/{id}`, this returns an error rather than `null` when the fee can't be quoted.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/batches/{id}/label": { "put": { "operationId": "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Batch ID.", "example": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBulkWithdrawalBatchLabelRequest" }, "example": { "label": "November rent (final)" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" }, "example": { "id": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f", "label": "November rent (final)", "currency": "ZAR", "totalAmount": "45000.00", "withdrawalCount": 3, "status": "PENDING_APPROVAL", "uploadedBy": "2e4a6c8e-0b1d-4f3a-9c5e-7a9b1d3f5a7c", "uploadedByName": { "name": "Lerato", "surname": "Mokoena" }, "approvedBy": null, "approvedByName": null, "approvedAt": null, "createdAt": "2026-10-22T14:03:11.250Z", "updatedAt": "2026-10-23T08:32:05.118Z", "completedAt": null, "feeQuote": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_UPDATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_UPDATE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ], "summary": "Rename a disbursement batch", "description": "Changes a batch's label.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/batches/{id}/withdrawals": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Batch ID.", "example": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "APPROVED", "EXECUTING", "SUBMITTED", "PROCESSING", "PAID", "FAILED", "SKIPPED" ] }, "description": "Only withdrawals with this status.", "example": "FAILED" }, { "name": "failureCode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GENERIC", "INSUFFICIENT_FUNDS", "INVALID_DETAILS", "NO_BANK_ACCOUNT", "AMOUNT_TOO_SMALL", "ACCOUNT_UNVERIFIED", "SYSTEM_UNAVAILABLE", "DECLINED", "REVERSED", "NO_PAYOUT_RESULT", "INVALID_REFERENCE" ] }, "description": "Only failed withdrawals with this failure category.", "example": "REVERSED" }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only withdrawals whose status changed, or whose fee was refunded, at or after this time. ISO 8601 with a time zone.", "example": "2026-10-23T08:00:00Z" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Page size, from 1 to 200; values outside that range are clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedBulkWithdrawalForDisplay" }, "example": { "items": [ { "id": "c4e8a2b6-3d5f-4a1c-9e7b-2f4d6a8c0e1b", "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d", "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "uploadedByName": null, "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "approvedByName": null, "amount": "12500.75", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountType": "CHEQUE", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "reference": "OCT SALARY", "linkedBankAccountId": null, "withdrawalId": "0f3b5d7e-9a1c-4e2f-8b4d-6c8e0a2b4d6f", "status": "PAID", "failureReason": null, "failureReasonCode": null, "feeReversed": false, "createdAt": "2026-10-23T08:15:01.912Z", "updatedAt": "2026-10-23T09:02:44.118Z", "lastChangedAt": "2026-10-23T09:02:44.118Z" } ], "total": 1, "limit": 50, "offset": 0, "truncated": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ], "summary": "List a batch's withdrawals", "description": "Returns the withdrawals in a batch, newest first, a page at a time. Use `updatedSince` to fetch only the withdrawals that changed since you last checked.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/beneficiaries": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsBeneficiaries", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text to search for in the name, trading name, email address and account number. Results are ranked by relevance and `sort` is ignored.", "example": "nkosi" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] }, "description": "Only beneficiaries of this type. Beneficiaries saved from a batch without a type match neither value. Case-insensitive.", "example": "INDIVIDUAL" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED", "ALL" ], "default": "ACTIVE" }, "description": "`ACTIVE`, `ARCHIVED` or `ALL`. Case-insensitive.", "example": "ACTIVE" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created", "lastPaid", "archived" ] }, "description": "`created` (newest first), `lastPaid` (most recently paid first, never paid last) or `archived` (most recently archived first). Defaults to `archived` when `status` is `ARCHIVED`, otherwise `created`; `archived` needs `status` `ARCHIVED` or `ALL`.", "example": "lastPaid" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Page size, from 1 to 200; values outside that range are clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedBeneficiaryForDisplay" }, "example": { "items": [ { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "email": "thandi@example.com", "type": "INDIVIDUAL", "tradingName": null, "reference": "SALARY", "country": "ZA", "createdAt": "2026-09-01T10:12:30.004Z", "updatedAt": "2026-10-23T08:15:02.010Z", "lastPaidAt": "2026-10-23T08:15:03.204Z", "deletedAt": null, "deletedBy": null } ], "total": 1, "limit": 50, "offset": 0, "truncated": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List beneficiaries", "description": "Returns your beneficiaries a page at a time, active ones by default. Use `query` to search by name, trading name, email address or account number.", "tags": [ "Beneficiaries" ] }, "post": { "operationId": "postV2PaymentsBulkWithdrawalsBeneficiaries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiaryRequest" }, "example": { "bank": "FNB", "accountHolder": "Thandi Nkosi", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "type": "INDIVIDUAL", "email": "thandi@example.com", "reference": "SALARY", "country": "ZA" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" }, "example": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "email": "thandi@example.com", "type": "INDIVIDUAL", "tradingName": null, "reference": "SALARY", "country": "ZA", "createdAt": "2026-09-01T10:12:30.004Z", "updatedAt": "2026-09-01T10:12:30.004Z", "lastPaidAt": null, "deletedAt": null, "deletedBy": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.CONFLICT": { "summary": "CONFLICT (CONFLICT)", "value": { "code": "CONFLICT", "message": "Resource conflict." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_CREATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_CREATE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "An active beneficiary with this bank and account number already exists; update it instead." } ], "summary": "Create a beneficiary", "description": "Saves a beneficiary you can pay out to. If an archived beneficiary has the same bank and account number, it's restored with these details and keeps its original ID.", "tags": [ "Beneficiaries" ] } }, "/v2/payments/bulk-withdrawals/beneficiaries/{id}": { "delete": { "operationId": "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Beneficiary ID.", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_DELETE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_DELETE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The beneficiary ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No active beneficiary with this ID exists on your account; it may already be archived." } ], "summary": "Archive a beneficiary", "description": "Archives a beneficiary so it no longer appears in the active list. Its bank and account number stay reserved: creating or paying the same recipient again restores it.", "tags": [ "Beneficiaries" ] }, "get": { "operationId": "getV2PaymentsBulkWithdrawalsBeneficiariesById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Beneficiary ID.", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" }, "example": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "email": "thandi@example.com", "type": "INDIVIDUAL", "tradingName": null, "reference": "SALARY", "country": "ZA", "createdAt": "2026-09-01T10:12:30.004Z", "updatedAt": "2026-10-23T08:15:02.010Z", "lastPaidAt": "2026-10-23T08:15:03.204Z", "deletedAt": null, "deletedBy": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The beneficiary ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No beneficiary with this ID exists on your account." } ], "summary": "Get a beneficiary", "description": "Returns a beneficiary, active or archived.", "tags": [ "Beneficiaries" ] }, "put": { "operationId": "putV2PaymentsBulkWithdrawalsBeneficiariesById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Beneficiary ID.", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBeneficiaryRequest" }, "example": { "bank": "FNB", "accountHolder": "Thandi Nkosi", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "SAVINGS", "type": "INDIVIDUAL", "email": "thandi.nkosi@example.com", "reference": "SALARY", "country": "ZA" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" }, "example": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "SAVINGS", "email": "thandi.nkosi@example.com", "type": "INDIVIDUAL", "tradingName": null, "reference": "SALARY", "country": "ZA", "createdAt": "2026-09-01T10:12:30.004Z", "updatedAt": "2026-10-23T11:05:48.902Z", "lastPaidAt": null, "deletedAt": null, "deletedBy": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.CONFLICT": { "summary": "CONFLICT (CONFLICT)", "value": { "code": "CONFLICT", "message": "Resource conflict." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_UPDATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_UPDATE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No active beneficiary with this ID exists on your account; archived beneficiaries can't be updated." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "Another beneficiary, active or archived, already has this bank and account number." } ], "summary": "Update a beneficiary", "description": "Replaces every field of an active beneficiary; optional fields you leave out are cleared. Changing the bank or account number fails if another beneficiary, including an archived one, already has them.", "tags": [ "Beneficiaries" ] } }, "/v2/payments/bulk-withdrawals/beneficiaries/bulk": { "post": { "operationId": "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiariesRequest" }, "example": { "beneficiaries": [ { "bank": "FNB", "accountHolder": "Thandi Nkosi", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "type": "INDIVIDUAL", "email": "thandi@example.com", "reference": "SALARY", "country": "ZA" }, { "bank": "STANDARD", "accountHolder": "Karoo Fresh Produce (Pty) Ltd", "accountNumber": "271934058", "branchCode": "051001", "accountType": "CHEQUE", "type": "BUSINESS", "tradingName": "Karoo Fresh", "email": "accounts@example.com", "country": "ZA" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } }, "example": [ { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "accountType": "CHEQUE", "email": "thandi@example.com", "type": "INDIVIDUAL", "tradingName": null, "reference": "SALARY", "country": "ZA", "createdAt": "2026-09-01T10:12:30.004Z", "updatedAt": "2026-10-23T10:20:15.380Z", "lastPaidAt": null, "deletedAt": null, "deletedBy": null }, { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "bank": "STANDARD", "bankDisplayName": "Standard Bank", "accountHolder": "Karoo Fresh Produce (Pty) Ltd", "accountNumberMasked": "*****4058", "accountNumber": "271934058", "branchCode": "051001", "accountType": "CHEQUE", "email": "accounts@example.com", "type": "BUSINESS", "tradingName": "Karoo Fresh", "reference": null, "country": "ZA", "createdAt": "2026-10-23T10:20:15.380Z", "updatedAt": "2026-10-23T10:20:15.380Z", "lastPaidAt": null, "deletedAt": null, "deletedBy": null } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_CREATE", "x-valr-bundles": [ "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_CREATE", "bundles": [ "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "Create beneficiaries in bulk", "description": "Saves a list of beneficiaries in one all-or-nothing request and returns them in the order sent. A beneficiary with the same bank and account number as an existing one updates it, restoring it if archived, instead of failing.", "tags": [ "Beneficiaries" ] } }, "/v2/payments/bulk-withdrawals/fee-quote": { "post": { "operationId": "postV2PaymentsBulkWithdrawalsFeeQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeQuoteRequest" }, "example": { "withdrawals": [ { "bank": "FNB", "amount": 12500.75 }, { "bank": "CAPITEC", "amount": 8000.25 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" }, "example": { "fee": "25.00", "currency": "ZAR", "withdrawalCount": 2, "grossTotal": "20501.00", "requiredTotal": "20526.00", "feeGroups": [ { "actionType": "FAST_WITHDRAWAL", "withdrawalCount": 1, "grossTotal": "12500.75" }, { "actionType": "REGULAR_WITHDRAWAL", "withdrawalCount": 1, "grossTotal": "8000.25" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "Quote fees for withdrawals", "description": "Estimates the fee for a set of withdrawals before you create a batch, without saving anything. `requiredTotal` is the available balance your payout account needs for the payouts plus the fee.", "tags": [ "Disbursements" ] } }, "/v2/payments/bulk-withdrawals/withdrawals": { "get": { "operationId": "getV2PaymentsBulkWithdrawalsWithdrawals", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "APPROVED", "EXECUTING", "SUBMITTED", "PROCESSING", "PAID", "FAILED", "SKIPPED" ] }, "description": "Only withdrawals with this status.", "example": "FAILED" }, { "name": "failureCode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GENERIC", "INSUFFICIENT_FUNDS", "INVALID_DETAILS", "NO_BANK_ACCOUNT", "AMOUNT_TOO_SMALL", "ACCOUNT_UNVERIFIED", "SYSTEM_UNAVAILABLE", "DECLINED", "REVERSED", "NO_PAYOUT_RESULT", "INVALID_REFERENCE" ] }, "description": "Only failed withdrawals with this failure category.", "example": "INSUFFICIENT_FUNDS" }, { "name": "beneficiaryId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only withdrawals to this beneficiary.", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Page size, from 1 to 200; values outside that range are clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWithdrawalWithBatchForDisplay" }, "example": { "items": [ { "id": "c4e8a2b6-3d5f-4a1c-9e7b-2f4d6a8c0e1b", "amount": "12500.75", "bank": "FNB", "bankDisplayName": "FNB/RMB", "accountType": "CHEQUE", "accountHolder": "Thandi Nkosi", "accountNumberMasked": "*******0327", "accountNumber": "62845190327", "branchCode": "250655", "reference": "OCT SALARY", "linkedBankAccountId": null, "withdrawalId": "0f3b5d7e-9a1c-4e2f-8b4d-6c8e0a2b4d6f", "status": "PAID", "failureReason": null, "failureReasonCode": null, "createdAt": "2026-10-23T08:15:01.912Z", "updatedAt": "2026-10-23T09:02:44.118Z", "batch": { "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d", "label": "October salaries", "status": "COMPLETED", "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "uploadedByName": null, "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a", "approvedByName": null } } ], "total": 1, "limit": 50, "offset": 0, "truncated": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List withdrawals", "description": "Returns withdrawals across all your batches, newest first, each with a summary of its batch.", "tags": [ "Disbursements" ] } }, "/v2/payments/payout/history": { "get": { "operationId": "getV2PaymentsPayoutHistory", "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DEBIT", "CREDIT" ] }, "description": "`DEBIT` for money out (payouts) or `CREDIT` for money in (funding and reversals). Case-insensitive.", "example": "DEBIT" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "COMPLETE", "PROCESSING", "REVERSED", "FAILED" ] }, "description": "Only transactions with this status. Case-insensitive.", "example": "COMPLETE" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only transactions at or after this time, in Unix milliseconds.", "example": 1790812800000 }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Only transactions before this time, in Unix milliseconds.", "example": 1793491200000 }, { "name": "minAmount", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Only transactions of at least this amount, before fees.", "example": 1000 }, { "name": "maxAmount", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Only transactions of at most this amount, before fees.", "example": 50000 }, { "name": "exactAmount", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Only transactions of exactly this amount, before fees.", "example": 12500.75 }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text to find in the payment reference or batch label.", "example": "salaries" }, { "name": "beneficiaryId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only payouts to this beneficiary.", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Page size, from 1 to 200; values outside that range are clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPayoutTransactionForDisplay" }, "example": { "items": [ { "id": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b", "direction": "DEBIT", "kind": "WITHDRAWAL", "status": "COMPLETE", "amount": "12513.25", "currency": "ZAR", "date": 1792746164000, "counterparty": "Thandi Nkosi", "reference": "OCT SALARY", "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d", "batchLabel": "October salaries", "paymentId": null }, { "id": "4a6c8e0b-2d4f-4a1c-9e3b-5d7f9a1c3e5b", "direction": "CREDIT", "kind": "FUNDING", "status": "COMPLETE", "amount": "50000.00", "currency": "ZAR", "date": 1792654200000, "counterparty": "Payout account", "reference": "Funding", "batchId": null, "batchLabel": null, "paymentId": "f9a1c3e5-7b2d-4f6a-8c0e-1d3f5a7b9c2e" } ], "total": 2, "limit": 50, "offset": 0, "truncated": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ], "summary": "List payout account transactions", "description": "Returns the transactions on your payout account, newest first: debits for payouts, and credits for funding and reversed payouts. A reversed payout keeps its original debit, marked `REVERSED`, alongside a credit for the amount returned.", "tags": [ "Disbursements" ] } }, "/v2/payments/payout/history/{id}": { "get": { "operationId": "getV2PaymentsPayoutHistoryById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transaction ID.", "example": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutTransactionForDisplay" }, "example": { "id": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b", "direction": "DEBIT", "kind": "WITHDRAWAL", "status": "COMPLETE", "amount": "12513.25", "currency": "ZAR", "date": 1792746164000, "counterparty": "Thandi Nkosi", "reference": "OCT SALARY", "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d", "batchLabel": "October salaries", "paymentId": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "PaymentsErrorCode.BAD_REQUEST": { "summary": "BAD_REQUEST (BAD_REQUEST)", "value": { "code": "BAD_REQUEST", "message": "Bad request." } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED": { "summary": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED (-16098)", "value": { "code": -16098, "message": "Payments access is not configured for this user." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PaymentsErrorCode.NOT_FOUND": { "summary": "NOT_FOUND (NOT_FOUND)", "value": { "code": "NOT_FOUND", "message": "Resource not found." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "PaymentsErrorCode.INTERNAL_ERROR": { "summary": "INTERNAL_ERROR (INTERNAL_ERROR)", "value": { "code": "INTERNAL_ERROR", "message": "An internal error occurred." } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReturnErrorMessage" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "ApplicationErrorCodes.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (-16097)", "value": { "code": -16097, "message": "Upstream service error." } }, "PaymentsErrorCode.EXCHANGE_API_ERROR": { "summary": "EXCHANGE_API_ERROR (EXCHANGE_API_ERROR)", "value": { "code": "EXCHANGE_API_ERROR", "message": "Upstream service error." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED": { "summary": "PAYMENTS_BACKEND_PROXY_DISABLED (-16099)", "value": { "code": -16099, "message": "Payments backend is not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DISBURSEMENTS_READ", "x-valr-bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ], "x-valr-permissions": [ { "name": "DISBURSEMENTS_READ", "bundles": [ "PAYMENTS_READ", "DISBURSEMENTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The transaction ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payout account transaction with this ID exists on your account." } ], "summary": "Get a payout account transaction", "description": "Returns one transaction on your payout account.", "tags": [ "Disbursements" ] } }, "/v1/wallet/crypto/{currency}/deposit/address": { "get": { "operationId": "getV1WalletCryptoByCurrencyDepositAddress", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Crypto currency to deposit, e.g. `USDT`.", "example": "USDT" }, { "name": "networkType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Network to deposit on, e.g. `Ethereum`. Defaults to the currency's default network.", "example": "Ethereum" }, { "name": "accountType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "COLLECTIONS", "FUNDING", "PAYOUTS" ] }, "description": "Payments account to get the address for, instead of the account the request acts on: `COLLECTIONS`, `FUNDING` or `PAYOUTS` (case-insensitive). Only takes effect together with `destinationCurrency`; if you send just one of the two, both are ignored.", "example": "FUNDING" }, { "name": "destinationCurrency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Currency the payments account chosen with `accountType` is set up for, e.g. `ZAR` for a funding account whose deposits are converted to rand. Only takes effect together with `accountType`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1FundAddress" }, "example": { "currency": "USDT", "address": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812", "networkType": "Ethereum" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.CURRENCY_NOT_SUPPORTED": { "summary": "CURRENCY_NOT_SUPPORTED (-112)", "value": { "code": -112, "message": "Currency not supported" } }, "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH": { "summary": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH (-15721)", "value": { "code": -15721, "message": "No scoped deposit account exists for the requested currency." } }, "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE": { "summary": "RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE (-13105)", "value": { "code": -13105, "message": "Deposit address is not supported for the specified currency and network type" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION": { "summary": "RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION (-13104)", "value": { "code": -13104, "message": "Deposit address is not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.COULD_NOT_GET_RECEIVE_ADDRESS": { "summary": "COULD_NOT_GET_RECEIVE_ADDRESS (-30)", "value": { "code": -30, "message": "Could not get deposit address" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency or `destinationCurrency` isn't recognised, or `accountType` is blank or isn't `COLLECTIONS`, `FUNDING` or `PAYOUTS`." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "`networkType` wasn't sent and the currency can't be deposited on a blockchain, for example a fiat currency." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your business has no account of the requested `accountType` set up for `destinationCurrency`." }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "code": -13104, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "httpStatus": 403, "message": "Deposit address is not supported in your region", "reason": "The account has no address for this currency and network yet, and crypto deposits are restricted for your business, so a new one can't be created." }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "code": -13105, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "httpStatus": 400, "message": "Deposit address is not supported for the specified currency and network type", "reason": "The account has no address for this currency and network yet, and deposits on this network are disabled or not supported for this currency." }, { "ref": "ErrorCodes.COULD_NOT_GET_RECEIVE_ADDRESS", "code": -30, "name": "COULD_NOT_GET_RECEIVE_ADDRESS", "httpStatus": 500, "message": "Could not get deposit address", "reason": "A new deposit address couldn't be created. Try again later." } ], "summary": "Get a crypto deposit address", "description": "Returns the deposit address for a currency on one network for the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), creating one if the account doesn't have one yet. To get the address of one of your business's payments accounts instead, send `accountType` and `destinationCurrency` together; a key restricted to sub-accounts can't do this.", "tags": [ "Crypto deposits" ] } }, "/v1/wallet/crypto/{currency}/deposit/history": { "get": { "operationId": "getV1WalletCryptoByCurrencyDepositHistory", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency of the deposits, e.g. `USDT`.", "example": "USDT" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of deposits to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of deposits to return, up to 100.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only deposits detected at or after this time (ISO 8601, UTC).", "example": "2026-10-01T00:00:00Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only deposits detected before this time (ISO 8601, UTC).", "example": "2026-11-01T00:00:00Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1BlockchainReceiveTransactionForApi" } }, "example": [ { "currencyCode": "USDT", "networkType": "Ethereum", "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812", "transactionHash": "0x5c5cd31c2f3ad5bf9ad71fa665e55033ae42f046d7c8124c25a234265190901e", "amount": "250", "createdAt": "2026-10-23T08:40:02Z", "confirmations": 3, "confirmed": false }, { "currencyCode": "USDT", "networkType": "Ethereum", "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812", "transactionHash": "0x532c1d6c2d1aaae73bfbd818126c4853b0af2a081ad72ccbf716094a011e6bbc", "amount": "1500", "createdAt": "2026-10-22T14:03:19Z", "confirmations": 12, "confirmed": true, "confirmedAt": "2026-10-22T14:06:41.205Z" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ], "summary": "List crypto deposits for a currency", "description": "Returns deposits of one currency to the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first, including deposits still waiting for confirmations.", "tags": [ "Crypto deposits" ] } }, "/v1/wallet/crypto/{currency}/withdraw": { "get": { "operationId": "getV1WalletCryptoByCurrencyWithdraw", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Crypto currency, e.g. `USDC`.", "example": "USDC" }, { "name": "networkType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Network to get the settings for, e.g. `Ethereum`. Defaults to the currency's default network.", "example": "Ethereum" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WithdrawDetailsForApi" }, "example": { "currency": "USDC", "minimumWithdrawAmount": "10", "withdrawalDecimalPlaces": "6", "isActive": true, "withdrawCost": "1.5", "networkType": "Ethereum", "supportsPaymentReference": false } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.CURRENCY_NOT_SUPPORTED": { "summary": "CURRENCY_NOT_SUPPORTED (-112)", "value": { "code": -112, "message": "Currency not supported" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "`networkType` wasn't sent and the currency can't be withdrawn on a blockchain, for example a fiat currency." } ], "summary": "Get crypto withdrawal settings", "description": "Returns the minimum amount, network fee and decimal places for withdrawing a currency on one network, and whether withdrawals on it are open. Amounts with more decimal places than `withdrawalDecimalPlaces` are rounded down when you withdraw.", "tags": [ "Crypto withdrawals" ] }, "post": { "operationId": "postV1WalletCryptoByCurrencyWithdraw", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency to withdraw, e.g. `USDC`.", "example": "USDC" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SendCryptoRequest" }, "example": { "amount": "250", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "networkType": "Ethereum", "beneficiaryName": "Acme Treasury (Pty) Ltd", "isCorporate": true, "isSelfHosted": false, "serviceProviderId": "676d1c189ef2fd542e5bbf33" } } } }, "responses": { "202": { "description": "Withdrawal accepted for processing. The body is `{\"id\": \"\"}`, for example `{\"id\": \"7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c\"}`. The withdrawal can still fail later, so follow it with `GET /v1/wallet/crypto/{currency}/withdraw/{id}`." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED": { "summary": "NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED (-13427)", "value": { "code": -13427, "message": "Withdrawals to addresses not in your address book are disabled. Please contact support to change" } }, "ErrorCodes.ADDRESS_BOOK_ENTRY_STILL_WARMING_UP": { "summary": "ADDRESS_BOOK_ENTRY_STILL_WARMING_UP (-13428)", "value": { "code": -13428, "message": "Address book entry too new. Withdrawals not allowed yet" } }, "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED": { "summary": "WITHDRAWALS_TEMPORARILY_SUSPENDED (-13415)", "value": { "code": -13415, "message": "Withdrawals have been suspended" } }, "ErrorCodes.CURRENCY_NOT_SUPPORTED": { "summary": "CURRENCY_NOT_SUPPORTED (-112)", "value": { "code": -112, "message": "Currency not supported" } }, "ApplicationErrorCodes.BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY": { "summary": "BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY (-13018)", "value": { "code": -13018, "message": "Unable to validate network type for provided currency" } }, "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE": { "summary": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE (-13402)", "value": { "code": -13402, "message": "This currency does not support a payment reference field" } }, "ErrorCodes.PAYMENT_REFERENCE_MISSING": { "summary": "PAYMENT_REFERENCE_MISSING (-13410)", "value": { "code": -13410, "message": "This withdrawal address requires a " } }, "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE": { "summary": "INVALID_WITHDRAW_TRANSACTION_REFERENCE (-13405)", "value": { "code": -13405, "message": "Invalid transaction reference" } }, "ErrorCodes.INVALID_WITHDRAW_ADDRESS": { "summary": "INVALID_WITHDRAW_ADDRESS (-50)", "value": { "code": -50, "message": "Invalid Withdraw address." } }, "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM": { "summary": "WITHDRAW_AMOUNT_BELOW_MINIMUM (-13411)", "value": { "code": -13411, "message": "Please ensure withdrawal amount is larger than " } }, "ErrorCodes.INVALID_WITHDRAW_AMOUNT": { "summary": "INVALID_WITHDRAW_AMOUNT (-13404)", "value": { "code": -13404, "message": "Invalid withdraw amount, please ensure amount is larger than minimum" } }, "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED": { "summary": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED (-13419)", "value": { "code": -13419, "message": "Withdrawals to this address are not allowed" } }, "ApplicationErrorCodes.BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID": { "summary": "BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID (-13017)", "value": { "code": -13017, "message": "Unable to verify trustline. Please confirm that your address has an active trustline for this asset." } }, "ApplicationErrorCodes.BLOCKCHAIN_SEND_MISSING_KYC_PERMIT": { "summary": "BLOCKCHAIN_SEND_MISSING_KYC_PERMIT (-13019)", "value": { "code": -13019, "message": "Contact token issuer for whitelisting." } }, "ApplicationErrorCodes.SERVICE_PROVIDER_NOT_FOUND": { "summary": "SERVICE_PROVIDER_NOT_FOUND (-30071)", "value": { "code": -30071, "message": "Service provider not found." } }, "ErrorCodes.INSUFFICIENT_BALANCE": { "summary": "INSUFFICIENT_BALANCE (-6)", "value": { "code": -6, "message": "Insufficient Balance" } }, "ErrorCodes.WITHDRAW_LIMIT_REACHED": { "summary": "WITHDRAW_LIMIT_REACHED (-108)", "value": { "code": -108, "message": "Amount exceeds daily limit" } }, "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED": { "summary": "WITHDRAWAL_RESTRICTION_APPLIED (-32765)", "value": { "code": -32765, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal." } }, "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT": { "summary": "MARGIN_NOT_ENABLED_FOR_ACCOUNT (-19213)", "value": { "code": -19213, "message": "Margin not enabled for account" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE (-19243)", "value": { "code": -19243, "message": "Borrowing for withdrawal and internal transfers currently not available" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY (-19244)", "value": { "code": -19244, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.ADDRESS_BOOK_ENTRY_NOT_FOUND": { "summary": "ADDRESS_BOOK_ENTRY_NOT_FOUND (-13422)", "value": { "code": -13422, "message": "Could not find address book entry." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.ADDRESS_BOOK_ENTRY_CURRENCY_WRONG": { "summary": "ADDRESS_BOOK_ENTRY_CURRENCY_WRONG (-13423)", "value": { "code": -13423, "message": "Address book entry not valid for specified currency" } }, "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE": { "summary": "CURRENCY_UNDER_MAINTENANCE (-19502)", "value": { "code": -19502, "message": "Currency currently under maintenance. Please try again in a few minutes." } }, "ErrorCodes.WITHDRAW_UNAVAILABLE": { "summary": "WITHDRAW_UNAVAILABLE (-46)", "value": { "code": -46, "message": "Withdrawal currently unavailable." } }, "ErrorCodes.BLOCKCHAIN_SEND_FAILURE": { "summary": "BLOCKCHAIN_SEND_FAILURE (-29)", "value": { "code": -29, "message": "Unknown Blockchain Send Failure" } }, "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW": { "summary": "INSUFFICIENT_LIQUIDITY_FOR_BORROW (-19202)", "value": { "code": -19202, "message": "The borrow amount is unavailable currently, please try again later" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE": { "summary": "WITHDRAWALS_NOT_AVAILABLE (-12015)", "value": { "code": -12015, "message": "Withdrawals are currently not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_CREATE", "x-valr-bundles": [ "WITHDRAWALS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_CREATE", "bundles": [ "WITHDRAWALS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised, or the body fails validation, for example `amount` isn't a positive decimal, both or neither of `address` and `addressBookId` are sent, or the recipient's details are missing; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_NOT_FOUND", "code": -13422, "name": "ADDRESS_BOOK_ENTRY_NOT_FOUND", "httpStatus": 404, "message": "Could not find address book entry.", "reason": "No entry with this `addressBookId` exists in the account's address book." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "code": -13423, "name": "ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "httpStatus": 500, "message": "Address book entry not valid for specified currency", "reason": "The address-book entry is saved for a different currency." }, { "ref": "ErrorCodes.NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "code": -13427, "name": "NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "httpStatus": 400, "message": "Withdrawals to addresses not in your address book are disabled. Please contact support to change", "reason": "Withdrawals are restricted to address-book entries, and the address isn't saved in the account's address book." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "code": -13428, "name": "ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "httpStatus": 400, "message": "Address book entry too new. Withdrawals not allowed yet", "reason": "Withdrawals are restricted to address-book entries, and this entry was added or changed too recently. Try again once its waiting period has passed." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused after a recent security change on your account; the message says when they resume. Withdrawals to address-book entries may still be allowed." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "The currency is under maintenance. Try again in a few minutes." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "The currency can't be withdrawn on a blockchain, for example a fiat currency." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "code": -13018, "name": "BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "httpStatus": 400, "message": "Unable to validate network type for provided currency", "reason": "The network isn't available for this currency." }, { "ref": "ErrorCodes.WITHDRAW_UNAVAILABLE", "code": -46, "name": "WITHDRAW_UNAVAILABLE", "httpStatus": 500, "message": "Withdrawal currently unavailable.", "reason": "Withdrawals of this currency on this network are currently disabled, or the withdrawal couldn't be recorded. Try again later." }, { "ref": "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "code": -13402, "name": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "httpStatus": 400, "message": "This currency does not support a payment reference field", "reason": "A `paymentReference` was sent, but this currency and network don't use one." }, { "ref": "ErrorCodes.PAYMENT_REFERENCE_MISSING", "code": -13410, "name": "PAYMENT_REFERENCE_MISSING", "httpStatus": 400, "message": "This withdrawal address requires a ", "reason": "The address needs a payment reference, such as a memo or tag; send it in `paymentReference`." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE", "code": -13405, "name": "INVALID_WITHDRAW_TRANSACTION_REFERENCE", "httpStatus": 400, "message": "Invalid transaction reference", "reason": "The `paymentReference` isn't valid for this network." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_ADDRESS", "code": -50, "name": "INVALID_WITHDRAW_ADDRESS", "httpStatus": 400, "message": "Invalid Withdraw address.", "reason": "The address isn't valid for this currency and network." }, { "ref": "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM", "code": -13411, "name": "WITHDRAW_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Please ensure withdrawal amount is larger than ", "reason": "The amount is below the network's minimum, which the message gives." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_AMOUNT", "code": -13404, "name": "INVALID_WITHDRAW_AMOUNT", "httpStatus": 400, "message": "Invalid withdraw amount, please ensure amount is larger than minimum", "reason": "The network rejected the amount, for example because it has too many decimal places." }, { "ref": "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "code": -13419, "name": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "httpStatus": 400, "message": "Withdrawals to this address are not allowed", "reason": "Sending to this address would need more network fee than is allowed, so it can't receive withdrawals." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "code": -13017, "name": "BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "httpStatus": 400, "message": "Unable to verify trustline. Please confirm that your address has an active trustline for this asset.", "reason": "The destination address has no active trustline for this asset." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "code": -13019, "name": "BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "httpStatus": 400, "message": "Contact token issuer for whitelisting.", "reason": "The token issuer hasn't whitelisted the destination address." }, { "ref": "ErrorCodes.BLOCKCHAIN_SEND_FAILURE", "code": -29, "name": "BLOCKCHAIN_SEND_FAILURE", "httpStatus": 500, "message": "Unknown Blockchain Send Failure", "reason": "The withdrawal couldn't be checked with the network. Try again later." }, { "ref": "ApplicationErrorCodes.SERVICE_PROVIDER_NOT_FOUND", "code": -30071, "name": "SERVICE_PROVIDER_NOT_FOUND", "httpStatus": 400, "message": "Service provider not found.", "reason": "`serviceProviderId` isn't in the list from `GET /v1/wallet/crypto/service-providers`." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover the amount plus the network fee." }, { "ref": "ErrorCodes.WITHDRAW_LIMIT_REACHED", "code": -108, "name": "WITHDRAW_LIMIT_REACHED", "httpStatus": 400, "message": "Amount exceeds daily limit", "reason": "The withdrawal would exceed your business's withdrawal limit; see `GET /v1/wallet/crypto/{currency}/withdraw/limits`." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "Your business must keep a minimum portfolio value, and this withdrawal would take it below that." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` is `true`, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` is `true`, but borrowing for withdrawals is currently unavailable." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` is `true`, but this currency can't be borrowed for withdrawals." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` is `true`, but the amount can't be borrowed right now. Try again later." } ], "summary": "Withdraw crypto", "description": "Sends crypto from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to `address`, or to the entry in that account's address book given by `addressBookId`. The network fee from `GET /v1/wallet/crypto/{currency}/withdraw` is charged on top of `amount` (sends to another VALR account are free), and if your business only allows withdrawals to address-book entries, the address must already be saved there and past its waiting period.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/crypto/{currency}/withdraw/{id}": { "get": { "operationId": "getV1WalletCryptoByCurrencyWithdrawById", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency of the withdrawal, e.g. `USDC`. It must match the withdrawal's currency.", "example": "USDC" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Withdrawal ID returned when the withdrawal was created (`uniqueId` in responses).", "example": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BlockchainSendTransactionForApi" }, "example": { "currency": "USDC", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "amount": "250", "feeAmount": "1.5", "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84", "confirmations": 12, "lastConfirmationAt": "2026-10-23T08:21:47.318205", "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c", "createdAt": "2026-10-23T08:15:02.441Z", "verified": true, "status": "Complete", "networkType": "Ethereum" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.SEND_NOT_FOUND": { "summary": "SEND_NOT_FOUND (-13403)", "value": { "code": -13403, "message": "Could not find send" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised or the withdrawal ID isn't a valid UUID." }, { "ref": "ErrorCodes.SEND_NOT_FOUND", "code": -13403, "name": "SEND_NOT_FOUND", "httpStatus": 404, "message": "Could not find send", "reason": "No withdrawal with this ID exists on the account, or it's in a different currency." } ], "summary": "Get a crypto withdrawal", "description": "Returns one withdrawal from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), with its status, network fee and, once it has been broadcast, its transaction hash and confirmations.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/crypto/{currency}/withdraw/history": { "get": { "operationId": "getV1WalletCryptoByCurrencyWithdrawHistory", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency of the withdrawals, e.g. `USDC`.", "example": "USDC" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of withdrawals to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of withdrawals to return, up to 100.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only withdrawals created at or after this time (ISO 8601, UTC).", "example": "2026-10-01T00:00:00Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only withdrawals created before this time (ISO 8601, UTC).", "example": "2026-11-01T00:00:00Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1BlockchainSendTransactionForApi" } }, "example": [ { "currency": "USDC", "address": "0x2a7c4e9b1d3f5a6c8e0b2d4f6a8c0e2b4d6f8a1c", "amount": "1200", "feeAmount": "1.5", "confirmations": 0, "uniqueId": "e4b2a1c9-8d7f-4e3a-b6c5-0f9e8d7c6b5a", "createdAt": "2026-10-23T09:02:37.106Z", "verified": true, "status": "Processing", "networkType": "Ethereum" }, { "currency": "USDC", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "amount": "250", "feeAmount": "1.5", "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84", "confirmations": 12, "lastConfirmationAt": "2026-10-23T08:21:47.318205", "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c", "createdAt": "2026-10-23T08:15:02.441Z", "verified": true, "status": "Complete", "networkType": "Ethereum" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ], "summary": "List crypto withdrawals for a currency", "description": "Returns withdrawals of one currency from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first. Cancelled withdrawals are left out, so a page can hold fewer than `limit` items.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/crypto/{currency}/withdraw/limits": { "get": { "operationId": "getV1WalletCryptoByCurrencyWithdrawLimits", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency to give the remaining limit in, e.g. `BTC`.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WithdrawLimitDetailsForApi" }, "example": { "limitType": "daily", "totalWithdrawnAmountInReferenceCurrency": "0.15000000", "withdrawLimitAmountInReferenceCurrency": "10.00000000", "referenceCurrency": "BTC", "maxWithdrawAmountInWithdrawCurrency": "9.85000000", "withdrawCurrency": "BTC" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." } ], "summary": "Get crypto withdrawal limits", "description": "Returns your business's withdrawal limit, valued in BTC, how much of it has been used, and the most you can still withdraw in this currency. Limits apply to your whole business, so the result is the same whichever account the request acts on.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/crypto/address-book": { "get": { "operationId": "getV1WalletCryptoAddressBook", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of entries to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of entries to return, up to 100.", "example": 100 }, { "name": "networkType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only entries on this network, e.g. `Ethereum`.", "example": "Ethereum" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1AddressBookEntryForApi" } }, "example": [ { "id": "3b8e1f6a-2c4d-4e5f-8a9b-0c1d2e3f4a5b", "label": "Treasury cold wallet", "currency": "BTC", "address": "bc1q4u7h2kz9x8w3n5e6r0t2y7m8c9v3f5g6j8k2l0", "networkType": "Bitcoin", "createdAt": "2026-09-14T10:22:31.508Z", "type": "CURRENCY_SPECIFIC", "beneficiaryName": "Acme Treasury (Pty) Ltd", "isCorporate": true, "isSelfHosted": true }, { "id": "9f2a7c3e-4b5d-4e6f-a7b8-c9d0e1f2a3b4", "label": "Exchange settlement (Ethereum)", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "networkType": "Ethereum", "createdAt": "2026-10-02T13:05:47.219Z", "type": "UNIVERSAL", "beneficiaryName": "Acme Treasury (Pty) Ltd", "isCorporate": true, "isSelfHosted": false, "serviceProviderName": "Binance", "serviceProviderId": "676d1c189ef2fd542e5bbf33" }, { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "label": "Supplier USDC (Stellar)", "currency": "USDC", "address": "GBXK7Q2M4N6P8R0T2V4X6Z8B0D2F4H6J8L0N2P4R6T8V0X2Z4B6D8F", "networkType": "StellarLumens", "paymentReference": "INV-20431", "createdAt": "2026-10-12T07:41:09.880Z", "type": "CURRENCY_SPECIFIC", "beneficiaryName": "Northwind Supplies Ltd", "isCorporate": true, "isSelfHosted": false, "serviceProviderName": "Example Custody" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank." } ], "summary": "List address-book entries", "description": "Returns the saved withdrawal addresses in the address book of the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), oldest first. Send an entry's `id` as `addressBookId` to withdraw to it.", "tags": [ "Address book" ] } }, "/v1/wallet/crypto/address-book/{currency}": { "get": { "operationId": "getV1WalletCryptoAddressBookByCurrency", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency to list entries for, e.g. `USDC`.", "example": "USDC" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of entries to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of entries to return, up to 100.", "example": 100 }, { "name": "networkType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only entries on this network, e.g. `Ethereum`.", "example": "Ethereum" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1AddressBookEntryForApi" } }, "example": [ { "id": "9f2a7c3e-4b5d-4e6f-a7b8-c9d0e1f2a3b4", "label": "Exchange settlement (Ethereum)", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "networkType": "Ethereum", "createdAt": "2026-10-02T13:05:47.219Z", "type": "UNIVERSAL", "beneficiaryName": "Acme Treasury (Pty) Ltd", "isCorporate": true, "isSelfHosted": false, "serviceProviderName": "Binance", "serviceProviderId": "676d1c189ef2fd542e5bbf33" }, { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "label": "Supplier USDC (Stellar)", "currency": "USDC", "address": "GBXK7Q2M4N6P8R0T2V4X6Z8B0D2F4H6J8L0N2P4R6T8V0X2Z4B6D8F", "networkType": "StellarLumens", "paymentReference": "INV-20431", "createdAt": "2026-10-12T07:41:09.880Z", "type": "CURRENCY_SPECIFIC", "beneficiaryName": "Northwind Supplies Ltd", "isCorporate": true, "isSelfHosted": false, "serviceProviderName": "Example Custody" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised, `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank." } ], "summary": "List address-book entries for a currency", "description": "Returns the address-book entries of the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) that you can withdraw this currency to: entries saved for the currency plus universal entries on its networks, oldest first.", "tags": [ "Address book" ] } }, "/v1/wallet/crypto/deposit/history": { "get": { "operationId": "getV1WalletCryptoDepositHistory", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of deposits to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of deposits to return, up to 100.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only deposits detected at or after this time (ISO 8601, UTC).", "example": "2026-10-01T00:00:00Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only deposits detected before this time (ISO 8601, UTC).", "example": "2026-11-01T00:00:00Z" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only deposits in this currency, e.g. `USDT`. Leave out for all currencies.", "example": "USDT" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1BlockchainReceiveTransactionForApi" } }, "example": [ { "currencyCode": "USDT", "networkType": "Ethereum", "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812", "transactionHash": "0x5c5cd31c2f3ad5bf9ad71fa665e55033ae42f046d7c8124c25a234265190901e", "amount": "250", "createdAt": "2026-10-23T08:40:02Z", "confirmations": 3, "confirmed": false }, { "currencyCode": "USDT", "networkType": "Ethereum", "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812", "transactionHash": "0x532c1d6c2d1aaae73bfbd818126c4853b0af2a081ad72ccbf716094a011e6bbc", "amount": "1500", "createdAt": "2026-10-22T14:03:19Z", "confirmations": 12, "confirmed": true, "confirmedAt": "2026-10-22T14:06:41.205Z" }, { "currencyCode": "BTC", "networkType": "Bitcoin", "receiveAddress": "bc1q4u7h2kz9x8w3n5e6r0t2y7m8c9v3f5g6j8k2l0", "transactionHash": "c61bd9c633f3dc91eaf6bec6c3812b5542bf83a243076954f10a743a48d5f48e", "amount": "0.05", "createdAt": "2026-10-21T09:12:44Z", "confirmations": 6, "confirmed": true, "confirmedAt": "2026-10-21T10:08:13.917Z" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ], "summary": "List crypto deposits", "description": "Returns crypto deposits to the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first, including deposits still waiting for confirmations. Filter by currency with `currency`.", "tags": [ "Crypto deposits" ] } }, "/v1/wallet/crypto/service-providers": { "get": { "operationId": "getV1WalletCryptoServiceProviders", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VaspItem" } }, "example": [ { "id": "672b1ff8a1ff8a027906ff39", "name": "Bybit", "hidden": false }, { "id": "676d1c189ef2fd542e5bbf33", "name": "Binance", "hidden": false } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true } ], "summary": "List service providers", "description": "Returns the exchanges and other crypto service providers you can name as a withdrawal recipient's provider, by sending an `id` as `serviceProviderId`. If the recipient's provider isn't listed, send its name in `serviceProviderName` instead.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/crypto/withdraw/history": { "get": { "operationId": "getV1WalletCryptoWithdrawHistory", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of withdrawals to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of withdrawals to return, up to 100.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only withdrawals created at or after this time (ISO 8601, UTC).", "example": "2026-10-01T00:00:00Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only withdrawals created before this time (ISO 8601, UTC).", "example": "2026-11-01T00:00:00Z" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only withdrawals in this currency, e.g. `USDC`. Leave out for all currencies.", "example": "USDC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1BlockchainSendTransactionForApi" } }, "example": [ { "currency": "USDC", "address": "0x2a7c4e9b1d3f5a6c8e0b2d4f6a8c0e2b4d6f8a1c", "amount": "1200", "feeAmount": "1.5", "confirmations": 0, "uniqueId": "e4b2a1c9-8d7f-4e3a-b6c5-0f9e8d7c6b5a", "createdAt": "2026-10-23T09:02:37.106Z", "verified": true, "status": "Processing", "networkType": "Ethereum" }, { "currency": "USDC", "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c", "amount": "250", "feeAmount": "1.5", "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84", "confirmations": 12, "lastConfirmationAt": "2026-10-23T08:21:47.318205", "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c", "createdAt": "2026-10-23T08:15:02.441Z", "verified": true, "status": "Complete", "networkType": "Ethereum" }, { "currency": "BTC", "address": "bc1q7m3k9x2v5n8c4z6w1q0p3r5t7y9u2i4o6a8s0d", "amount": "0.25", "feeAmount": "0.0001", "transactionHash": "16297f4bc279b9085dff06661db1c251012bdb1f6044587d923d71958a13edb3", "confirmations": 6, "lastConfirmationAt": "2026-10-20T11:47:05.662190", "uniqueId": "3f8a6d2c-1b9e-4c7a-8e5d-2a4b6c8d0e1f", "createdAt": "2026-10-20T10:58:19.027Z", "verified": true, "status": "Complete", "networkType": "Bitcoin" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ], "summary": "List crypto withdrawals", "description": "Returns crypto withdrawals from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first; filter by currency with `currency`. Cancelled withdrawals are left out, so a page can hold fewer than `limit` items.", "tags": [ "Crypto withdrawals" ] } }, "/v1/wallet/fiat/{currency}/accounts": { "get": { "operationId": "getV1WalletFiatByCurrencyAccounts", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the bank accounts, e.g. `ZAR`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1LinkedBankAccountForApi" } }, "example": [ { "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15", "bank": "FNB/RMB", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "62792461544", "branchCode": "250655", "accountType": "Current/Cheque", "createdAt": "2026-08-14T09:21:37.408215Z", "country": "ZA" }, { "id": "8f2a6d10-c3e4-4b7f-a915-2e7c0b9d4f68", "bank": "Standard Bank", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "10094857261", "branchCode": "051001", "accountType": "Current/Cheque", "createdAt": "2026-09-30T13:05:12.774031Z", "country": "ZA" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." } ], "summary": "List bank accounts", "description": "Lists the bank accounts linked to the account for this currency, oldest first. Bank accounts belong to one account: the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`.", "tags": [ "Bank accounts" ] }, "post": { "operationId": "postV1WalletFiatByCurrencyAccounts", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency the bank account receives, e.g. `ZAR`.", "example": "ZAR" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingLinkedBankAccount" }, "example": { "bank": "FNB", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "62792461544", "branchCode": "250655", "accountType": "CHEQUE", "country": "ZA" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1LinkedBankAccountForDisplay" }, "example": { "id": "b71d4e93-2a6f-4c08-8e5b-d93f1a7c2e40", "bankCode": "FNB", "bankName": "FNB/RMB", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "62792461544", "branchCode": "250655", "accountType": "Current/Cheque", "status": "CONFIRMED", "insertedAt": "2026-10-23T08:14:02.518236Z", "updatedAt": "2026-10-23T08:14:02.611904Z", "country": "ZA", "currency": { "symbol": "R", "decimalPlaces": 2, "isActive": true, "shortName": "ZAR", "longName": "Rand", "supportedWithdrawDecimalPlaces": 2, "collateral": true, "collateralWeight": "1" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED": { "summary": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED (-15875)", "value": { "code": -15875, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support." } }, "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED": { "summary": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED (-13418)", "value": { "code": -13418, "message": "Bank account linking has been temporarily suspended" } }, "ErrorCodes.INVALID_COUNTRY_ALPHA_2": { "summary": "INVALID_COUNTRY_ALPHA_2 (-115)", "value": { "code": -115, "message": "Invalid country alpha 2" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.BANK_REMOTE_FETCH_FAILURE": { "summary": "BANK_REMOTE_FETCH_FAILURE (-15317)", "value": { "code": -15317, "message": "Unable to fetch remote list of banks" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "BANK_ACCOUNTS_MANAGE", "x-valr-bundles": [ "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "BANK_ACCOUNTS_MANAGE", "bundles": [ "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `bank` that isn't in the country's bank list or a branch code, account number or account type that doesn't fit the country, or the currency isn't recognised; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Withdrawals to this branch code aren't supported. Use another branch or contact support." }, { "ref": "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "code": -13418, "name": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "httpStatus": 400, "message": "Bank account linking has been temporarily suspended", "reason": "Linking bank accounts is paused for a while after a security change on your account, such as a password reset or a new device; the message says when it's re-enabled." }, { "ref": "ErrorCodes.INVALID_COUNTRY_ALPHA_2", "code": -115, "name": "INVALID_COUNTRY_ALPHA_2", "httpStatus": 400, "message": "Invalid country alpha 2", "reason": "No banks are available for the bank account's country." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list for the bank account's country couldn't be loaded. Try again later." } ], "summary": "Link a bank account", "description": "Links a bank account for fiat withdrawals to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). It's active straight away, with no email or two-factor confirmation; for currencies that only pay out to verified bank accounts, withdrawals to it are refused until it shows `VERIFIED`. Take `bank` from List banks for a currency; `accountType` is `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION` for South African accounts.", "tags": [ "Bank accounts" ] } }, "/v1/wallet/fiat/{currency}/accounts/{id}": { "delete": { "operationId": "deleteV1WalletFiatByCurrencyAccountsById", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency, e.g. `ZAR`.", "example": "ZAR" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Bank account ID: the `id` returned when it was linked or listed.", "example": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15" } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT": { "summary": "COULD_NOT_GET_LINKED_ACCOUNT (-14203)", "value": { "code": -14203, "message": "The requested bank account does not exist" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "BANK_ACCOUNTS_MANAGE", "x-valr-bundles": [ "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "BANK_ACCOUNTS_MANAGE", "bundles": [ "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The bank account ID isn't a valid UUID, or the `Content-Type: application/json` header is missing." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID is linked to the account." } ], "summary": "Delete a bank account", "description": "Deletes a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) so it can't receive withdrawals any more. Send a `Content-Type: application/json` header even though the request has no body.", "tags": [ "Bank accounts" ] }, "get": { "operationId": "getV1WalletFiatByCurrencyAccountsById", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency, e.g. `ZAR`.", "example": "ZAR" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Bank account ID: the `id` returned when it was linked or listed.", "example": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1LinkedBankAccountForApi" }, "example": { "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15", "bank": "FNB/RMB", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "62792461544", "branchCode": "250655", "accountType": "Current/Cheque", "createdAt": "2026-08-14T09:21:37.408215Z", "country": "ZA" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT": { "summary": "COULD_NOT_GET_LINKED_ACCOUNT (-14203)", "value": { "code": -14203, "message": "The requested bank account does not exist" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised or the bank account ID isn't a valid UUID." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID is linked to the account." } ], "summary": "Get a bank account", "description": "Returns a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`).", "tags": [ "Bank accounts" ] } }, "/v1/wallet/fiat/{currency}/banks": { "get": { "operationId": "getV1WalletFiatByCurrencyBanks", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency, e.g. `ZAR`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankForDisplay" } }, "example": [ { "code": "ABSA", "displayName": "ABSA Bank", "defaultBranchCode": "632005", "rtcParticipant": true, "rtgsParticipant": true, "countryCode": "ZA" }, { "code": "CAPITEC", "displayName": "Capitec Bank", "defaultBranchCode": "470010", "rtcParticipant": true, "rtgsParticipant": false, "countryCode": "ZA" }, { "code": "FNB", "displayName": "FNB/RMB", "defaultBranchCode": "250655", "rtcParticipant": true, "rtgsParticipant": true, "countryCode": "ZA" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.CURRENCY_NOT_SUPPORTED": { "summary": "CURRENCY_NOT_SUPPORTED (-112)", "value": { "code": -112, "message": "Currency not supported" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.BANK_REMOTE_FETCH_FAILURE": { "summary": "BANK_REMOTE_FETCH_FAILURE (-15317)", "value": { "code": -15317, "message": "Unable to fetch remote list of banks" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "Bank accounts can't be linked in this currency." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list couldn't be loaded. Try again later." } ], "summary": "List banks for a currency", "description": "Lists the banks you can link a bank account at for this currency, with each bank's default branch code and whether it takes real-time (RTC) and RTGS payments. Use a bank's `code` as `bank` when you link a bank account.", "tags": [ "Bank accounts" ] } }, "/v1/wallet/fiat/{currency}/deposit/reference": { "get": { "operationId": "getV1WalletFiatByCurrencyDepositReference", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency you'll deposit, e.g. `ZAR`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDepositReferenceForDisplay" }, "example": { "reference": "VR4KQ7ZP2M" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY (-15111)", "value": { "code": -15111, "message": "Deposits in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "code": -15111, "name": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Deposits in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow deposits in this currency." } ], "summary": "Get the account deposit reference", "description": "Returns the reference to quote when you deposit this currency by bank transfer, so the deposit is credited to the account: the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`. Each account has its own reference, created the first time you ask for it.", "tags": [ "Fiat deposits" ] } }, "/v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}": { "get": { "operationId": "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency you'll deposit, e.g. `ZAR`.", "example": "ZAR" }, { "name": "buyCurrencySymbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency to buy with the deposit, e.g. `BTC`.", "example": "BTC" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDepositReferenceForDisplay" }, "example": { "reference": "BTC4NQ8ZKW" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.INVALID_CURRENCY_PAIR": { "summary": "INVALID_CURRENCY_PAIR (-21)", "value": { "code": -21, "message": "Unsupported Currency Pair" } }, "ErrorCodes.CURRENCY_PAIR_NOT_ACTIVE": { "summary": "CURRENCY_PAIR_NOT_ACTIVE (-32)", "value": { "code": -32, "message": "The given currency pair is not active" } }, "ErrorCodes.CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY": { "summary": "CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY (-15132)", "value": { "code": -15132, "message": "Currency not enabled for Auto-Buy" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY": { "summary": "CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY (-15134)", "value": { "code": -15134, "message": "Auto-buys in the selected currency are not supported in your region" } }, "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY (-15111)", "value": { "code": -15111, "message": "Deposits in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`currency` or `buyCurrencySymbol` isn't a recognised currency." }, { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "There's no market for buying `buyCurrencySymbol` with `currency`." }, { "ref": "ErrorCodes.CURRENCY_PAIR_NOT_ACTIVE", "code": -32, "name": "CURRENCY_PAIR_NOT_ACTIVE", "httpStatus": 400, "message": "The given currency pair is not active", "reason": "The market for buying `buyCurrencySymbol` with `currency` isn't active." }, { "ref": "ErrorCodes.CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15132, "name": "CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 400, "message": "Currency not enabled for Auto-Buy", "reason": "`buyCurrencySymbol` can't be auto-bought with `currency`; list the currencies that can with List auto-buy currencies." }, { "ref": "ErrorCodes.CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15134, "name": "CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 451, "message": "Auto-buys in the selected currency are not supported in your region", "reason": "Auto-buy into `buyCurrencySymbol` with `currency` isn't available for your business." }, { "ref": "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "code": -15111, "name": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Deposits in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow deposits in `currency`." } ], "summary": "Get an auto-buy deposit reference", "description": "Returns an auto-buy reference: a deposit in `currency` that quotes it is credited to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) and used to buy `buyCurrencySymbol`. List the currencies you can buy with List auto-buy currencies.", "tags": [ "Fiat deposits" ] } }, "/v1/wallet/fiat/{currency}/auto-buy": { "get": { "operationId": "getV1WalletFiatByCurrencyAutoBuy", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency you'll deposit, e.g. `ZAR`.", "example": "ZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "BTC", "ETH", "SOL" ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "DEPOSITS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "DEPOSITS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." } ], "summary": "List auto-buy currencies", "description": "Lists the currencies that a deposit in this currency can buy automatically when it quotes an auto-buy reference. The list depends on your business's region, and is empty if auto-buy isn't available for the currency.", "tags": [ "Fiat deposits" ] } }, "/v1/wallet/fiat/{currency}/withdraw/estimate-fee": { "get": { "operationId": "getV1WalletFiatByCurrencyWithdrawEstimateFee", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency to withdraw, e.g. `ZAR`.", "example": "ZAR" }, { "name": "linkedBankAccountId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the bank account to withdraw to.", "example": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Amount to withdraw, as a decimal string.", "example": "1500" }, { "name": "fast", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`true` to price a fast (RTC or RTGS) withdrawal.", "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatWithdrawalFeeEstimateForDisplay" }, "example": { "feeAmount": "8.50", "fullAmount": "1500.00", "fast": false } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT": { "summary": "COULD_NOT_GET_LINKED_ACCOUNT (-14203)", "value": { "code": -14203, "message": "The requested bank account does not exist" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`linkedBankAccountId` is missing or isn't a UUID, `amount` is missing or isn't a number, `fast` isn't `true` or `false`, or the currency isn't recognised." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID exists." } ], "summary": "Estimate a fiat withdrawal fee", "description": "Returns the fee for withdrawing `amount` to a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). The fee is charged on top, so the account is debited `fullAmount` plus `feeAmount`.", "tags": [ "Fiat withdrawals" ] } }, "/v1/wallet/fiat/{currency}/withdraw": { "post": { "operationId": "postV1WalletFiatByCurrencyWithdraw", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency to withdraw, e.g. `ZAR`.", "example": "ZAR" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1IncomingNewFiatWithdrawal" }, "example": { "linkedBankAccountId": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15", "amount": "1500", "fast": false, "reference": "INV 2026-0142" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED": { "summary": "WITHDRAWALS_TEMPORARILY_SUSPENDED (-13415)", "value": { "code": -13415, "message": "Withdrawals have been suspended" } }, "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED": { "summary": "WITHDRAWAL_RESTRICTION_APPLIED (-32765)", "value": { "code": -32765, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal." } }, "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED": { "summary": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED (-15875)", "value": { "code": -15875, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support." } }, "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM": { "summary": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM (-15307)", "value": { "code": -15307, "message": "Amount is lower than the minimum" } }, "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH": { "summary": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH (-15318)", "value": { "code": -15318, "message": "Withdrawal currency does not match the currency of selected bank account" } }, "ErrorCodes.INSUFFICIENT_BALANCE": { "summary": "INSUFFICIENT_BALANCE (-6)", "value": { "code": -6, "message": "Insufficient Balance" } }, "ErrorCodes.CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT": { "summary": "CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT (-15322)", "value": { "code": -15322, "message": "This bank account has been deleted. Please add the account and try again." } }, "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT": { "summary": "CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT (-15321)", "value": { "code": -15321, "message": "This bank account is not confirmed. Please complete our verification process to withdraw." } }, "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT": { "summary": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT (-15309)", "value": { "code": -15309, "message": "This bank account is not verified. Please withdraw to a verified account." } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE (-19243)", "value": { "code": -19243, "message": "Borrowing for withdrawal and internal transfers currently not available" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY (-19244)", "value": { "code": -19244, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency" } }, "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT": { "summary": "MARGIN_NOT_ENABLED_FOR_ACCOUNT (-19213)", "value": { "code": -19213, "message": "Margin not enabled for account" } }, "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11533)", "value": { "code": -11533, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed." } }, "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11534)", "value": { "code": -11534, "message": "Account total borrow limit would be exceeded and is therefore not allowed." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT": { "summary": "COULD_NOT_GET_LINKED_ACCOUNT (-14203)", "value": { "code": -14203, "message": "The requested bank account does not exist" } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW": { "summary": "INSUFFICIENT_LIQUIDITY_FOR_BORROW (-19202)", "value": { "code": -19202, "message": "The borrow amount is unavailable currently, please try again later" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE": { "summary": "WITHDRAWALS_NOT_AVAILABLE (-12015)", "value": { "code": -12015, "message": "Withdrawals are currently not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_CREATE", "x-valr-bundles": [ "WITHDRAWALS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_CREATE", "bundles": [ "WITHDRAWALS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, or `reference` was rejected, or the currency isn't recognised; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The withdrawal would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with `linkedBankAccountId` exists." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Withdrawals to the bank account's branch code aren't supported. Use another bank account or contact support." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "code": -15307, "name": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Amount is lower than the minimum", "reason": "`amount` is below the minimum withdrawal for this currency." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "code": -15318, "name": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "httpStatus": 400, "message": "Withdrawal currency does not match the currency of selected bank account", "reason": "The bank account was linked for a different currency." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the fee." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "code": -15322, "name": "CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account has been deleted. Please add the account and try again.", "reason": "The bank account has been deleted. Link it again to withdraw to it." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "code": -15321, "name": "CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not confirmed. Please complete our verification process to withdraw.", "reason": "The bank account was never confirmed." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "code": -15309, "name": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not verified. Please withdraw to a verified account.", "reason": "This currency only pays out to verified bank accounts, and this one hasn't been verified yet or failed verification." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` was set, but this currency can't be borrowed for a withdrawal." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` was set, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` was set, but the amount to borrow isn't available right now. Try again later." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's total borrow limit." } ], "summary": "Withdraw fiat to a bank account", "description": "Withdraws fiat from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to a bank account linked to that same account, with no email or two-factor confirmation; the fee is charged on top of `amount`. Set `fast` for a real-time (RTC) or RTGS payment at participating banks, and `allowBorrow` to borrow any shortfall against your other assets on a margin-enabled account. The response holds the withdrawal's `id`; track it with Get a fiat withdrawal.", "tags": [ "Fiat withdrawals" ] } }, "/v1/wallet/fiat/{currency}/withdrawals": { "get": { "operationId": "getV1WalletFiatByCurrencyWithdrawals", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the withdrawals, e.g. `ZAR`.", "example": "ZAR" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return withdrawals with this status: `NEW` (created, nothing done yet), `PENDING_APPROVAL` (waiting for an approver), `PROCESSING` (debited and on its way to the bank), `PAID`, `REVERSED` (paid, then returned), `FAILED` (didn't complete and wasn't reversed) or `DECLINED` (declined in review or approval). A reversed withdrawal shows `FAILED` until the reversal completes. Leave it out for every status.", "example": "PAID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of withdrawals to return, from 1 to 200; values outside that range are adjusted.", "example": 50 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of withdrawals to skip, for paging. Negative values count as 0.", "example": 0 }, { "name": "includeAllSubAccounts", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`true` to include withdrawals from the primary and every sub-account apart from hidden ones. Only applies when you don't send `X-VALR-SUB-ACCOUNT-ID` and the key isn't restricted to sub-accounts; otherwise it's ignored.", "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatWithdrawalPageForV1Display" }, "example": { "items": [ { "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84", "subAccountId": "0", "currency": "ZAR", "amount": "1500.00", "status": "PAID", "linkedBankAccountId": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15", "isFast": false, "createdAt": "2026-10-23T08:30:05.272523Z", "updatedAt": "2026-10-23T11:02:41.167902Z", "feeAmount": "8.50" }, { "id": "5e9b3f17-a2c4-4d6e-8b91-0f4d7a2c6e33", "subAccountId": "0", "currency": "ZAR", "amount": "420.00", "status": "FAILED", "linkedBankAccountId": "8f2a6d10-c3e4-4b7f-a915-2e7c0b9d4f68", "isFast": true, "createdAt": "2026-10-20T14:12:44.091355Z", "updatedAt": "2026-10-20T14:40:18.630117Z", "feeAmount": "25.00", "failureReason": "INVALID_ACCOUNT_DETAILS", "failureReasonDescription": "The bank could not find an account with these details.", "failureReasonAction": "Check the account number, branch code and account type, update your bank account and try again.", "failureRetryable": false } ], "total": 2, "limit": 50, "offset": 0 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`status` is empty or isn't one of the listed values, `limit` or `offset` isn't a whole number, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised." } ], "summary": "List fiat withdrawals", "description": "Lists fiat withdrawals in this currency, newest first, for the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). `total` counts every match across pages; use it with `limit` and `offset` to page.", "tags": [ "Fiat withdrawals" ] } }, "/v1/wallet/fiat/{currency}/withdrawals/{id}": { "get": { "operationId": "getV1WalletFiatByCurrencyWithdrawalsById", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fiat currency of the withdrawal, e.g. `ZAR`.", "example": "ZAR" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Withdrawal ID: the `id` returned when the withdrawal was created.", "example": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84" }, { "name": "includeAllSubAccounts", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`true` to find the withdrawal on the primary or any sub-account apart from hidden ones. Only applies when you don't send `X-VALR-SUB-ACCOUNT-ID` and the key isn't restricted to sub-accounts; otherwise it's ignored.", "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatWithdrawalDetailForV1Display" }, "example": { "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84", "subAccountId": "0", "currency": "ZAR", "amount": "1500.00", "status": "PAID", "isFast": false, "createdAt": "2026-10-23T08:30:05.272523Z", "updatedAt": "2026-10-23T11:02:41.167902Z", "linkedBankAccount": { "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15", "bankCode": "FNB", "bankName": "FNB/RMB", "accountHolder": "Acme Trading (Pty) Ltd", "accountNumber": "62792461544", "branchCode": "250655", "accountType": "Current/Cheque", "status": "VERIFIED", "insertedAt": "2026-08-14T09:21:37.408215Z", "updatedAt": "2026-08-14T09:23:02.115480Z", "country": "ZA", "currency": { "symbol": "R", "decimalPlaces": 2, "isActive": true, "shortName": "ZAR", "longName": "Rand", "supportedWithdrawDecimalPlaces": 2, "collateral": true, "collateralWeight": "1" } }, "reference": "INV 2026-0142", "feeAmount": "8.50" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.COULD_NOT_FIND_FIAT_WITHDRAWAL": { "summary": "COULD_NOT_FIND_FIAT_WITHDRAWAL (-15300)", "value": { "code": -15300, "message": "The requested withdrawal does not exist" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "BANK_ACCOUNTS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The withdrawal ID isn't a valid UUID, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised." }, { "ref": "ErrorCodes.COULD_NOT_FIND_FIAT_WITHDRAWAL", "code": -15300, "name": "COULD_NOT_FIND_FIAT_WITHDRAWAL", "httpStatus": 404, "message": "The requested withdrawal does not exist", "reason": "No withdrawal in this currency with this ID exists on the account, or on any of your business's visible accounts when `includeAllSubAccounts` applies." } ], "summary": "Get a fiat withdrawal", "description": "Returns a fiat withdrawal with the bank account it was paid to, its fee and, if it was reversed, the amounts returned. It must belong to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), unless `includeAllSubAccounts` applies.", "tags": [ "Fiat withdrawals" ] } }, "/v2/fiat/payments": { "post": { "operationId": "postV2FiatPayments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingPaymentFiat" }, "example": { "amount": "2500.00", "currency": "ZAR", "newBeneficiary": { "bank": "STANDARD", "accountHolder": "Karoo Logistics (Pty) Ltd", "accountNumber": "10094857261", "branchCode": "051001", "accountType": "CHEQUE", "country": "ZA" }, "fast": true, "reference": "INV 2026-0187" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "id": "1f6c8a3e-5b2d-4e97-a0c4-8d3e6f1b9a57" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.INVALID_CURRENCY_SYMBOL": { "summary": "INVALID_CURRENCY_SYMBOL (-109)", "value": { "code": -109, "message": "Invalid currency symbol" } }, "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED": { "summary": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED (-18104)", "value": { "code": -18104, "message": "Provide either an existing beneficiary id or full beneficiary details." } }, "ErrorCodes.INVALID_COUNTRY_ALPHA_2": { "summary": "INVALID_COUNTRY_ALPHA_2 (-115)", "value": { "code": -115, "message": "Invalid country alpha 2" } }, "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED": { "summary": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED (-13418)", "value": { "code": -13418, "message": "Bank account linking has been temporarily suspended" } }, "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED": { "summary": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED (-15875)", "value": { "code": -15875, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support." } }, "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED": { "summary": "WITHDRAWALS_TEMPORARILY_SUSPENDED (-13415)", "value": { "code": -13415, "message": "Withdrawals have been suspended" } }, "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED": { "summary": "WITHDRAWAL_RESTRICTION_APPLIED (-32765)", "value": { "code": -32765, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal." } }, "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM": { "summary": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM (-15307)", "value": { "code": -15307, "message": "Amount is lower than the minimum" } }, "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH": { "summary": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH (-15318)", "value": { "code": -15318, "message": "Withdrawal currency does not match the currency of selected bank account" } }, "ErrorCodes.INSUFFICIENT_BALANCE": { "summary": "INSUFFICIENT_BALANCE (-6)", "value": { "code": -6, "message": "Insufficient Balance" } }, "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT": { "summary": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT (-15309)", "value": { "code": -15309, "message": "This bank account is not verified. Please withdraw to a verified account." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_API_DISABLED": { "summary": "PAYMENTS_API_DISABLED (-18106)", "value": { "code": -18106, "message": "API payments are not enabled." } }, "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT": { "summary": "COULD_NOT_GET_LINKED_ACCOUNT (-14203)", "value": { "code": -14203, "message": "The requested bank account does not exist" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE": { "summary": "PAYMENT_BENEFICIARY_NOT_ACTIVE (-18103)", "value": { "code": -18103, "message": "The selected payment beneficiary is not active." } } } } } }, "451": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY": { "summary": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY (-15320)", "value": { "code": -15320, "message": "Withdrawals in the selected currency are not supported in your region" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.BANK_REMOTE_FETCH_FAILURE": { "summary": "BANK_REMOTE_FETCH_FAILURE (-15317)", "value": { "code": -15317, "message": "Unable to fetch remote list of banks" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE": { "summary": "WITHDRAWALS_NOT_AVAILABLE (-12015)", "value": { "code": -12015, "message": "Withdrawals are currently not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_CREATE", "x-valr-bundles": [ "WITHDRAWALS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_CREATE", "bundles": [ "WITHDRAWALS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `newBeneficiary` field or a `newBeneficiary.bank` that isn't in the country's bank list, or `reference` was rejected; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_API_DISABLED", "code": -18106, "name": "PAYMENTS_API_DISABLED", "httpStatus": 404, "message": "API payments are not enabled.", "reason": "This endpoint isn't available yet." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currency` isn't a recognised currency." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "code": -18104, "name": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "httpStatus": 400, "message": "Provide either an existing beneficiary id or full beneficiary details.", "reason": "Neither `beneficiaryId` nor `newBeneficiary` was sent." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with `beneficiaryId` exists." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE", "code": -18103, "name": "PAYMENT_BENEFICIARY_NOT_ACTIVE", "httpStatus": 409, "message": "The selected payment beneficiary is not active.", "reason": "The beneficiary with `beneficiaryId` was never confirmed or has been deleted." }, { "ref": "ErrorCodes.INVALID_COUNTRY_ALPHA_2", "code": -115, "name": "INVALID_COUNTRY_ALPHA_2", "httpStatus": 400, "message": "Invalid country alpha 2", "reason": "No banks are available for `newBeneficiary`'s country." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list for `newBeneficiary`'s country couldn't be loaded. Try again later." }, { "ref": "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "code": -13418, "name": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "httpStatus": 400, "message": "Bank account linking has been temporarily suspended", "reason": "Adding a beneficiary is paused for a while after a security change on your account; the message says when it's re-enabled. You can still pay an existing beneficiary." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Payments to the beneficiary's branch code aren't supported. Use another bank account or contact support." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The payment would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "code": -15307, "name": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Amount is lower than the minimum", "reason": "`amount` is below the minimum withdrawal for this currency." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "code": -15318, "name": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "httpStatus": 400, "message": "Withdrawal currency does not match the currency of selected bank account", "reason": "The beneficiary's bank account was linked for a different currency from `currency`." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the fee." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "code": -15309, "name": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not verified. Please withdraw to a verified account.", "reason": "This currency only pays out to verified bank accounts, and the beneficiary hasn't been verified yet or failed verification." } ], "summary": "Pay a bank beneficiary", "description": "Pays a bank beneficiary from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) straight away, with no approval step: the one-call alternative to linking a bank account and then using Withdraw fiat to a bank account. Send `beneficiaryId` to pay a bank account already linked to that account, or `newBeneficiary` (the fields of Link a bank account) to link one and pay it in the same call; `currency` defaults to `ZAR`, the fee is charged on top of `amount`, and borrowing isn't available. The response holds the withdrawal's `id`; track it with Get a fiat withdrawal.", "tags": [ "Fiat withdrawals" ] } }, "/v2/crypto/payments": { "post": { "operationId": "postV2CryptoPayments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingPaymentCrypto" }, "example": { "amount": "0.015", "currency": "BTC", "beneficiaryId": "9d2b7e4f-1a6c-4f83-b5e0-6c9a3d7f2b18" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "id": "e8c41a7d-3f5b-4a92-8d6e-2b7f0c9a4e51" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.INVALID_CURRENCY_SYMBOL": { "summary": "INVALID_CURRENCY_SYMBOL (-109)", "value": { "code": -109, "message": "Invalid currency symbol" } }, "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED": { "summary": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED (-18104)", "value": { "code": -18104, "message": "Provide either an existing beneficiary id or full beneficiary details." } }, "ErrorCodes.ADDRESS_BOOK_ENTRY_LABEL_IN_USE": { "summary": "ADDRESS_BOOK_ENTRY_LABEL_IN_USE (-13426)", "value": { "code": -13426, "message": "The label provided is already in use." } }, "ErrorCodes.INVALID_WITHDRAW_ADDRESS": { "summary": "INVALID_WITHDRAW_ADDRESS (-50)", "value": { "code": -50, "message": "Invalid Withdraw address." } }, "ErrorCodes.PAYMENT_REFERENCE_MISSING": { "summary": "PAYMENT_REFERENCE_MISSING (-13410)", "value": { "code": -13410, "message": "This withdrawal address requires a " } }, "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE": { "summary": "INVALID_WITHDRAW_TRANSACTION_REFERENCE (-13405)", "value": { "code": -13405, "message": "Invalid transaction reference" } }, "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE": { "summary": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE (-13402)", "value": { "code": -13402, "message": "This currency does not support a payment reference field" } }, "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED": { "summary": "WITHDRAWALS_TEMPORARILY_SUSPENDED (-13415)", "value": { "code": -13415, "message": "Withdrawals have been suspended" } }, "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM": { "summary": "WITHDRAW_AMOUNT_BELOW_MINIMUM (-13411)", "value": { "code": -13411, "message": "Please ensure withdrawal amount is larger than " } }, "ErrorCodes.INVALID_WITHDRAW_AMOUNT": { "summary": "INVALID_WITHDRAW_AMOUNT (-13404)", "value": { "code": -13404, "message": "Invalid withdraw amount, please ensure amount is larger than minimum" } }, "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED": { "summary": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED (-13419)", "value": { "code": -13419, "message": "Withdrawals to this address are not allowed" } }, "ErrorCodes.INSUFFICIENT_BALANCE": { "summary": "INSUFFICIENT_BALANCE (-6)", "value": { "code": -6, "message": "Insufficient Balance" } }, "ErrorCodes.WITHDRAW_LIMIT_REACHED": { "summary": "WITHDRAW_LIMIT_REACHED (-108)", "value": { "code": -108, "message": "Amount exceeds daily limit" } }, "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED": { "summary": "WITHDRAWAL_RESTRICTION_APPLIED (-32765)", "value": { "code": -32765, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal." } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE (-19243)", "value": { "code": -19243, "message": "Borrowing for withdrawal and internal transfers currently not available" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY (-19244)", "value": { "code": -19244, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency" } }, "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT": { "summary": "MARGIN_NOT_ENABLED_FOR_ACCOUNT (-19213)", "value": { "code": -19213, "message": "Margin not enabled for account" } }, "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11533)", "value": { "code": -11533, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed." } }, "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11534)", "value": { "code": -11534, "message": "Account total borrow limit would be exceeded and is therefore not allowed." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENTS_API_DISABLED": { "summary": "PAYMENTS_API_DISABLED (-18106)", "value": { "code": -18106, "message": "API payments are not enabled." } }, "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_FOUND": { "summary": "PAYMENT_BENEFICIARY_NOT_FOUND (-18101)", "value": { "code": -18101, "message": "Payment beneficiary not found." } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE": { "summary": "PAYMENT_BENEFICIARY_NOT_ACTIVE (-18103)", "value": { "code": -18103, "message": "The selected payment beneficiary is not active." } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE": { "summary": "CURRENCY_UNDER_MAINTENANCE (-19502)", "value": { "code": -19502, "message": "Currency currently under maintenance. Please try again in a few minutes." } }, "ErrorCodes.WITHDRAW_UNAVAILABLE": { "summary": "WITHDRAW_UNAVAILABLE (-46)", "value": { "code": -46, "message": "Withdrawal currently unavailable." } }, "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW": { "summary": "INSUFFICIENT_LIQUIDITY_FOR_BORROW (-19202)", "value": { "code": -19202, "message": "The borrow amount is unavailable currently, please try again later" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE": { "summary": "WITHDRAWALS_NOT_AVAILABLE (-12015)", "value": { "code": -12015, "message": "Withdrawals are currently not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "WITHDRAWALS_CREATE", "x-valr-bundles": [ "WITHDRAWALS_WRITE" ], "x-valr-permissions": [ { "name": "WITHDRAWALS_CREATE", "bundles": [ "WITHDRAWALS_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `newBeneficiary` field or missing travel-rule details (`beneficiaryName`, `isCorporate`, `isSelfHosted`, and a service provider for a hosted wallet) for an address outside VALR; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_API_DISABLED", "code": -18106, "name": "PAYMENTS_API_DISABLED", "httpStatus": 404, "message": "API payments are not enabled.", "reason": "This endpoint isn't available yet." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currency` isn't a recognised currency." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "code": -18104, "name": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "httpStatus": 400, "message": "Provide either an existing beneficiary id or full beneficiary details.", "reason": "Neither `beneficiaryId` nor `newBeneficiary` was sent." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_FOUND", "code": -18101, "name": "PAYMENT_BENEFICIARY_NOT_FOUND", "httpStatus": 404, "message": "Payment beneficiary not found.", "reason": "No address-book entry with `beneficiaryId` exists on the account." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE", "code": -18103, "name": "PAYMENT_BENEFICIARY_NOT_ACTIVE", "httpStatus": 409, "message": "The selected payment beneficiary is not active.", "reason": "The address-book entry with `beneficiaryId` hasn't been activated." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "code": -13426, "name": "ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "httpStatus": 400, "message": "The label provided is already in use.", "reason": "Another address-book entry on the account already uses `newBeneficiary.label`." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_ADDRESS", "code": -50, "name": "INVALID_WITHDRAW_ADDRESS", "httpStatus": 400, "message": "Invalid Withdraw address.", "reason": "The beneficiary's address isn't valid for this currency and network." }, { "ref": "ErrorCodes.PAYMENT_REFERENCE_MISSING", "code": -13410, "name": "PAYMENT_REFERENCE_MISSING", "httpStatus": 400, "message": "This withdrawal address requires a ", "reason": "The beneficiary's address needs a payment reference, such as a memo or tag." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE", "code": -13405, "name": "INVALID_WITHDRAW_TRANSACTION_REFERENCE", "httpStatus": 400, "message": "Invalid transaction reference", "reason": "The beneficiary's payment reference isn't valid for this address." }, { "ref": "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "code": -13402, "name": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "httpStatus": 400, "message": "This currency does not support a payment reference field", "reason": "The beneficiary has a payment reference, but this currency and network don't use one." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "Withdrawals of this currency are paused for maintenance. Try again in a few minutes." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ErrorCodes.WITHDRAW_UNAVAILABLE", "code": -46, "name": "WITHDRAW_UNAVAILABLE", "httpStatus": 500, "message": "Withdrawal currently unavailable.", "reason": "Withdrawals of this currency on this network are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM", "code": -13411, "name": "WITHDRAW_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Please ensure withdrawal amount is larger than ", "reason": "`amount` is below the minimum withdrawal for this currency and network." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_AMOUNT", "code": -13404, "name": "INVALID_WITHDRAW_AMOUNT", "httpStatus": 400, "message": "Invalid withdraw amount, please ensure amount is larger than minimum", "reason": "`amount` isn't valid for this currency and network, for example it has too many decimal places." }, { "ref": "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "code": -13419, "name": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "httpStatus": 400, "message": "Withdrawals to this address are not allowed", "reason": "Withdrawals to the beneficiary's address aren't allowed because sending to it would cost too much in network fees." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the network fee." }, { "ref": "ErrorCodes.WITHDRAW_LIMIT_REACHED", "code": -108, "name": "WITHDRAW_LIMIT_REACHED", "httpStatus": 400, "message": "Amount exceeds daily limit", "reason": "The payment would exceed your daily withdrawal limit." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The payment would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` was set, but this currency can't be borrowed for a withdrawal." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` was set, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` was set, but the amount to borrow isn't available right now. Try again later." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's total borrow limit." } ], "summary": "Pay a crypto beneficiary", "description": "Sends crypto from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to an address-book beneficiary straight away, with no approval step. Send `beneficiaryId` for an active address-book entry on that account, or `newBeneficiary` to add one and pay it in the same call; the address, network and payment reference always come from the beneficiary, `currency` defaults to `BTC`, and the network's normal fee for `feePriority` is charged on top of `amount` (a `fee` in the body is ignored). The response holds the withdrawal's `id`; track it with `GET /v1/wallet/crypto/{currency}/withdraw/{id}`.", "tags": [ "Crypto withdrawals" ] } }, "/v1/account/transactionhistory": { "get": { "operationId": "getV1AccountTransactionhistory", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of transactions to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200 }, "description": "Maximum number of transactions to return, up to 200.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include transactions at or after this time, as an ISO 8601 timestamp in UTC.", "example": "2026-10-01T00:00:00.000Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include transactions at or before this time, as an ISO 8601 timestamp in UTC. Mustn't be before `startTime`.", "example": "2026-10-23T00:00:00.000Z" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include transactions that debit or credit this currency, e.g. `ZAR`.", "example": "ZAR" }, { "name": "transactionTypes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated transaction types to include, in upper case, e.g. `LIMIT_BUY,MARKET_BUY`. The values are the `transactionType.type` values in responses.", "example": "FIAT_DEPOSIT,FIAT_WITHDRAWAL,INTERNAL_TRANSFER" }, { "name": "beforeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only include transactions older than the transaction with this `id`.", "example": "019a0c4e-2f70-7a3b-8c4d-2e1f0a9b8c7d" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1APIUserTransactionRecord" } }, "example": [ { "transactionType": { "type": "LIMIT_SELL", "description": "Limit Sell" }, "debitCurrency": "BTC", "debitValue": "0.0025", "creditCurrency": "ZAR", "creditValue": "2981.525", "feeCurrency": "ZAR", "feeValue": "5.975", "eventAt": "2026-10-22T14:03:51.207Z", "additionalInfo": { "costPerCoin": 1195000, "costPerCoinSymbol": "R", "currencyPairSymbol": "BTCZAR", "orderId": "019a0c4e-2e91-7f4a-b2c8-1d6e3f5a7b90" }, "id": "019a0c4e-2f70-7a3b-8c4d-2e1f0a9b8c7d" }, { "transactionType": { "type": "INTERNAL_TRANSFER", "description": "Transfer" }, "debitCurrency": "USDC", "debitValue": "2500", "eventAt": "2026-10-22T09:30:12.884Z", "additionalInfo": { "reason": "SUB_ACCOUNT", "reasonDescription": "Transfer between subaccounts", "additional": "Transfer from Primary to Treasury", "transferId": "512874" }, "id": "019a0b47-3d24-7c58-b1e9-6a7b8c9d0e1f" }, { "transactionType": { "type": "FIAT_DEPOSIT", "description": "Deposit" }, "creditCurrency": "ZAR", "creditValue": "150000", "eventAt": "2026-10-21T07:45:03.112Z", "id": "019a05a1-c2e8-7f30-8d4a-1b2c3d4e5f60" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "TRANSACTION_HISTORY_READ", "x-valr-bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "TRANSACTION_HISTORY_READ", "bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime`, `currency` isn't a currency VALR supports, `transactionTypes` contains an unknown type, or `beforeId` isn't a valid UUID." } ], "summary": "List transactions", "description": "Lists transactions on the account you call it on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first: trades, deposits, withdrawals, transfers between your accounts, fees and other balance changes. Filter by type, currency or time range, and page with `skip` and `limit`, or by passing the `id` of the oldest transaction you've received as `beforeId`.", "tags": [ "Transaction history" ] } }, "/v1/account/transactionhistory/subaccounts": { "get": { "operationId": "getV1AccountTransactionhistorySubaccounts", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of transactions to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of transactions to return, up to 200.", "example": 100 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include transactions at or after this time, as an ISO 8601 timestamp in UTC. If you send only `startTime`, results run to 7 days after it or to now, whichever is earlier.", "example": "2026-10-20T00:00:00.000Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include transactions at or before this time, as an ISO 8601 timestamp in UTC; at most 7 days after `startTime`. If you send only `endTime`, results start 7 days before it.", "example": "2026-10-23T00:00:00.000Z" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only include transactions that debit or credit this currency, e.g. `USDC`.", "example": "USDC" }, { "name": "transactionTypes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated transaction types to include, in upper case, e.g. `LIMIT_BUY,MARKET_BUY`. The values are the `transactionType.type` values in responses.", "example": "INTERNAL_TRANSFER,MARKET_BUY" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1APISubAccountUserTransactions" } }, "example": [ { "id": "7340032581337088", "label": "Treasury", "transactions": [ { "transactionType": { "type": "MARKET_BUY", "description": "Market Buy" }, "debitCurrency": "ZAR", "debitValue": "18420", "creditCurrency": "USDT", "creditValue": "998.5", "feeCurrency": "USDT", "feeValue": "1.5", "eventAt": "2026-10-22T10:02:44.319Z", "additionalInfo": { "costPerCoin": 18.42, "costPerCoinSymbol": "R", "currencyPairSymbol": "USDTZAR", "orderId": "019a0b64-9f13-7d2a-8e4b-5c6d7e8f9a0b" }, "id": "019a0b64-a0c7-7b19-9f2e-3d4c5b6a7980" }, { "transactionType": { "type": "INTERNAL_TRANSFER", "description": "Transfer" }, "creditCurrency": "USDC", "creditValue": "2500", "eventAt": "2026-10-22T09:30:12.884Z", "additionalInfo": { "reason": "SUB_ACCOUNT", "reasonDescription": "Transfer between subaccounts", "additional": "Transfer from Primary to Treasury", "transferId": "512874" }, "id": "019a0b47-3d25-7e61-a4c2-8b9c0d1e2f3a" } ] }, { "id": "7339876125413376", "label": "Client Funds", "transactions": [ { "transactionType": { "type": "FIAT_DEPOSIT", "description": "Deposit" }, "creditCurrency": "ZAR", "creditValue": "42000", "eventAt": "2026-10-21T12:15:30.004Z", "id": "019a06c8-5b31-7a44-b6d1-2c3d4e5f6a7b" } ] } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "TRANSACTION_HISTORY_READ", "x-valr-bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "TRANSACTION_HISTORY_READ", "bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`beforeId` was sent (it isn't supported here), `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime` or more than 7 days after it, `currency` isn't a currency VALR supports, or `transactionTypes` contains an unknown type." } ], "summary": "List transactions for all sub-accounts", "description": "Lists transactions on all your sub-accounts in one call, grouped by sub-account and newest first within each. Only sub-accounts with matching transactions are included, and your primary account's own transactions aren't. Results cover at most 7 days; with no time range you get the last 24 hours. Sub-accounts are read in groups of 50, with `skip` and `limit` applied within each group, so with more than 50 sub-accounts you can get more than `limit` transactions. Call it on your primary account: on a sub-account it returns an empty list. Keys limited to some sub-accounts can't use it.", "tags": [ "Transaction history" ] } }, "/v1/account/balances/all": { "get": { "operationId": "getV1AccountBalancesAll", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1AccountCurrencyBalancesForApi" } }, "example": [ { "account": { "label": "Treasury", "id": "7340032581337088" }, "balances": [ { "currency": "USDC", "available": "24850.12", "reserved": "0", "total": "24850.12", "updatedAt": "2026-10-22T09:30:12.884Z", "lendReserved": "0", "borrowReserved": "0", "borrowedAmount": "0" }, { "currency": "USDT", "available": "998.5", "reserved": "0", "total": "998.5", "updatedAt": "2026-10-22T10:02:44.319Z", "lendReserved": "0", "borrowReserved": "0", "borrowedAmount": "0" } ] }, { "account": { "label": "Client Funds", "id": "7339876125413376" }, "balances": [] }, { "account": { "label": "Primary", "id": "0" }, "balances": [ { "currency": "ZAR", "available": "1265172.33", "reserved": "25000", "total": "1290172.33", "updatedAt": "2026-10-22T14:03:51.207Z", "lendReserved": "0", "borrowReserved": "0", "borrowedAmount": "0" }, { "currency": "BTC", "available": "0.4175", "reserved": "0", "total": "0.4175", "updatedAt": "2026-10-22T14:03:51.207Z", "lendReserved": "0", "borrowReserved": "0", "borrowedAmount": "0" } ] } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "ACCOUNT_BALANCES_READ", "x-valr-bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "VALR_PAY_WRITE" ], "x-valr-permissions": [ { "name": "ACCOUNT_BALANCES_READ", "bundles": [ "TRADING_READ", "TRADING_WRITE", "TREASURY_READ", "TREASURY_WRITE", "WITHDRAWALS_WRITE", "VALR_PAY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true } ], "summary": "Get balances for all accounts", "description": "Returns the balances of your primary account and each of its sub-accounts in one call: every currency with a balance, reserved amount or debt, grouped by account. Accounts with nothing in them are listed with an empty `balances` array, and your primary account (`id` `0`) comes last. Balances in your payments payout, collections and funding accounts aren't included; use Get payments account balances for those. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Balances" ] } }, "/v1/account/subaccounts": { "get": { "operationId": "getV1AccountSubaccounts", "parameters": [ { "name": "includeTags", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`true` to include each account's `accountTags`.", "example": true }, { "name": "includePayoutAccounts", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "`true` to include `autoPayoutLinkedBankAccountId` for accounts that pay out to a bank account automatically.", "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1SubAccountForApi" } }, "example": [ { "label": "Primary", "id": "0" }, { "label": "Treasury", "id": "7340032581337088" }, { "label": "Client Funds", "id": "7339876125413376" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "SUB_ACCOUNTS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "SUB_ACCOUNTS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`includeTags` or `includePayoutAccounts` isn't `true` or `false`." } ], "summary": "List sub-accounts", "description": "Lists your primary account (`id` `0`, label `Primary`) followed by its sub-accounts, newest first. Deleted sub-accounts, and your payments payout, collections and funding accounts, aren't listed. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Sub-accounts" ] } }, "/v1/account/subaccount/{accountPublicId}": { "get": { "operationId": "getV1AccountSubaccountByAccountPublicId", "parameters": [ { "name": "accountPublicId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Sub-account ID: the `id` returned by List sub-accounts.", "example": "7340032581337088" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SubAccountWithKycForApi" }, "example": { "id": "7340032581337088", "label": "Treasury" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.SUB_ACCOUNT_NOT_FOUND": { "summary": "SUB_ACCOUNT_NOT_FOUND (-11134)", "value": { "code": -11134, "message": "Subaccount not found" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "SUB_ACCOUNTS_READ", "x-valr-bundles": [ "TREASURY_READ", "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "SUB_ACCOUNTS_READ", "bundles": [ "TREASURY_READ", "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The sub-account ID isn't a whole number." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this ID. Your primary account (`0`) isn't a sub-account." } ], "summary": "Get a sub-account", "description": "Returns a sub-account's ID and name. A sub-account registered with its account holder's KYC details also returns those details, such as `firstName`, `lastName`, `identityNumber` and `email`. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Sub-accounts" ] } }, "/v1/account/subaccount": { "post": { "operationId": "postV1AccountSubaccount", "parameters": [ { "name": "isProprietarySubAccount", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Only matters if VALR has made KYC details mandatory for your sub-accounts: then `true` creates a sub-account with just a name, and with `false` the body must also include the account holder's KYC details.", "example": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1IncomingSubAccountRegisterRequest" }, "example": { "label": "Client Funds", "accountTags": [ "CLIENT_FUNDS" ] } } } }, "responses": { "200": { "description": "Created. The body holds the new sub-account's ID as a string in `id`.", "content": { "application/json": { "example": { "id": "7339876125413376" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ApplicationErrorCodes.INVALID_ACCOUNT_TAG_COMBINATION": { "summary": "INVALID_ACCOUNT_TAG_COMBINATION (-17214)", "value": { "code": -17214, "message": "Invalid account tag combination" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS": { "summary": "SUB_ACCOUNT_ALREADY_EXISTS (-11132)", "value": { "code": -11132, "message": "A subaccount with that label already exists" } }, "ErrorCodes.SUB_ACCOUNT_LIMIT_EXCEEDED": { "summary": "SUB_ACCOUNT_LIMIT_EXCEEDED (-11136)", "value": { "code": -11136, "message": "New subaccount limit exceeded" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS": { "summary": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS (-11423)", "value": { "code": -11423, "message": "Sub account with Id, E-mail or Cell number already exists" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "SUB_ACCOUNTS_MANAGE", "x-valr-bundles": [ "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "SUB_ACCOUNTS_MANAGE", "bundles": [ "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS", "code": -11132, "name": "SUB_ACCOUNT_ALREADY_EXISTS", "httpStatus": 403, "message": "A subaccount with that label already exists", "reason": "Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_LIMIT_EXCEEDED", "code": -11136, "name": "SUB_ACCOUNT_LIMIT_EXCEEDED", "httpStatus": 403, "message": "New subaccount limit exceeded", "reason": "Your business already has the maximum number of sub-accounts." }, { "ref": "ApplicationErrorCodes.INVALID_ACCOUNT_TAG_COMBINATION", "code": -17214, "name": "INVALID_ACCOUNT_TAG_COMBINATION", "httpStatus": 400, "message": "Invalid account tag combination", "reason": "`accountTags` contains a tag other than `CLIENT_FUNDS`." }, { "ref": "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "code": -11423, "name": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "httpStatus": 409, "message": "Sub account with Id, E-mail or Cell number already exists", "reason": "Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number." } ], "summary": "Create a sub-account", "description": "Creates a sub-account and returns its ID. Set `accountTags` to `[\"CLIENT_FUNDS\"]` to mark it as an account for your clients' funds. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Sub-accounts" ] }, "put": { "operationId": "putV1AccountSubaccount", "parameters": [ { "name": "isProprietarySubAccount", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Only matters if VALR has made KYC details mandatory for your sub-accounts: then `true` changes just the name, and with `false` the body must also include the account holder's KYC details.", "example": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1IncomingUpdateSubAccountRequest" }, "example": { "id": 7340032581337088, "label": "Treasury Reserve" } } } }, "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.SUB_ACCOUNT_NOT_FOUND": { "summary": "SUB_ACCOUNT_NOT_FOUND (-11134)", "value": { "code": -11134, "message": "Subaccount not found" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS": { "summary": "SUB_ACCOUNT_ALREADY_EXISTS (-11132)", "value": { "code": -11132, "message": "A subaccount with that label already exists" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS": { "summary": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS (-11423)", "value": { "code": -11423, "message": "Sub account with Id, E-mail or Cell number already exists" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "SUB_ACCOUNTS_MANAGE", "x-valr-bundles": [ "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "SUB_ACCOUNTS_MANAGE", "bundles": [ "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this `id`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS", "code": -11132, "name": "SUB_ACCOUNT_ALREADY_EXISTS", "httpStatus": 403, "message": "A subaccount with that label already exists", "reason": "Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`." }, { "ref": "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "code": -11423, "name": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "httpStatus": 409, "message": "Sub account with Id, E-mail or Cell number already exists", "reason": "Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number." } ], "summary": "Rename a sub-account", "description": "Changes a sub-account's name and responds with 202 and no body. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Sub-accounts" ] }, "delete": { "operationId": "deleteV1AccountSubaccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1IncomingDeactivateSubAccountRequest" }, "example": { "id": 7340032581337088 } } } }, "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.SUB_ACCOUNT_NOT_FOUND": { "summary": "SUB_ACCOUNT_NOT_FOUND (-11134)", "value": { "code": -11134, "message": "Subaccount not found" } }, "ErrorCodes.CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES": { "summary": "CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES (-11163)", "value": { "code": -11163, "message": "Cannot disable sub account with balances" } }, "ApplicationErrorCodes.CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT": { "summary": "CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT (-17217)", "value": { "code": -17217, "message": "Cannot disable a system-provisioned sub account" } }, "ApplicationErrorCodes.CANNOT_DISABLE_SHARED_SUB_ACCOUNT": { "summary": "CANNOT_DISABLE_SHARED_SUB_ACCOUNT (-17216)", "value": { "code": -17216, "message": "Cannot disable shared sub account" } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "SUB_ACCOUNTS_MANAGE", "x-valr-bundles": [ "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "SUB_ACCOUNTS_MANAGE", "bundles": [ "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this `id`." }, { "ref": "ErrorCodes.CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "code": -11163, "name": "CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "httpStatus": 400, "message": "Cannot disable sub account with balances", "reason": "The sub-account still holds funds, reserved amounts or debt. Cancel its open orders, transfer its funds out and repay any borrowing, then try again." }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "code": -17217, "name": "CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable a system-provisioned sub account", "reason": "VALR set this sub-account up for you, so it can't be deleted." }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "code": -17216, "name": "CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable shared sub account", "reason": "The sub-account is shared with another VALR user. Stop sharing it, then try again." } ], "summary": "Delete a sub-account", "description": "Deletes a sub-account, so it no longer appears in your account lists, and responds with 204. The sub-account must be empty first: no balances, reserved amounts or debt. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.", "tags": [ "Sub-accounts" ] } }, "/v1/account/subaccounts/transfer": { "post": { "operationId": "postV1AccountSubaccountsTransfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1IncomingSubAccountInternalTransferRequest" }, "example": { "fromId": 0, "toId": 7340032581337088, "currencyCode": "USDC", "amount": "2500", "allowBorrow": false } } } }, "responses": { "202": { "description": "Accepted. The body holds the transfer's ID as a string in `id`.", "content": { "application/json": { "example": { "id": "512874" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING": { "summary": "API_KEY_API_KEY_HEADER_MISSING (-11268)", "value": { "code": -11268, "message": "API key header missing: X-VALR-API-KEY" } }, "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING": { "summary": "API_KEY_SIGNATURE_HEADER_MISSING (-11269)", "value": { "code": -11269, "message": "API key header missing: X-VALR-SIGNATURE" } }, "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID": { "summary": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID (-11270)", "value": { "code": -11270, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP" } }, "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY": { "summary": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY (-11258)", "value": { "code": -11258, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED": { "summary": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED (-11259)", "value": { "code": -11259, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past" } }, "ErrorCodes.INVALID_JSON": { "summary": "INVALID_JSON (-113)", "value": { "code": -113, "message": "Invalid JSON payload" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } }, "ErrorCodes.INVALID_CURRENCY_SYMBOL": { "summary": "INVALID_CURRENCY_SYMBOL (-109)", "value": { "code": -109, "message": "Invalid currency symbol" } }, "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT": { "summary": "MARGIN_NOT_ENABLED_FOR_ACCOUNT (-19213)", "value": { "code": -19213, "message": "Margin not enabled for account" } }, "ErrorCodes.INSUFFICIENT_BALANCE": { "summary": "INSUFFICIENT_BALANCE (-6)", "value": { "code": -6, "message": "Insufficient Balance" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE (-19243)", "value": { "code": -19243, "message": "Borrowing for withdrawal and internal transfers currently not available" } }, "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY": { "summary": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY (-19244)", "value": { "code": -19244, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency" } }, "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11533)", "value": { "code": -11533, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed." } }, "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING": { "summary": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING (-11534)", "value": { "code": -11534, "message": "Account total borrow limit would be exceeded and is therefore not allowed." } } } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_INVALID": { "summary": "API_KEY_INVALID (-11264)", "value": { "code": -11264, "message": "API key or secret is invalid" } }, "ErrorCodes.API_KEY_INVALID_SIGNATURE": { "summary": "API_KEY_INVALID_SIGNATURE (-11252)", "value": { "code": -11252, "message": "Request has an invalid signature" } }, "ErrorCodes.API_KEY_IP_NOT_WHITELISTED": { "summary": "API_KEY_IP_NOT_WHITELISTED (-11272)", "value": { "code": -11272, "message": "The originating IP Address has not been whitelisted." } }, "ErrorCodes.UNAUTHORIZED": { "summary": "UNAUTHORIZED (-93)", "value": { "code": -93, "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED": { "summary": "API_KEY_ENDPOINT_NOT_ALLOWED (-11277)", "value": { "code": -11277, "message": "This API key does not have permission to access this endpoint" } }, "ErrorCodes.SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED": { "summary": "SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED (-11133)", "value": { "code": -11133, "message": "Internal transfer did not succeed" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.API_KEY_REQUEST_BLACKLISTED": { "summary": "API_KEY_REQUEST_BLACKLISTED (-11257)", "value": { "code": -11257, "message": "Duplicate message received" } }, "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW": { "summary": "INSUFFICIENT_LIQUIDITY_FOR_BORROW (-19202)", "value": { "code": -19202, "message": "The borrow amount is unavailable currently, please try again later" } }, "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE": { "summary": "CURRENCY_UNDER_MAINTENANCE (-19502)", "value": { "code": -19502, "message": "Currency currently under maintenance. Please try again in a few minutes." } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ApplicationErrorCodes.INTERNAL_TRANSFERS_NOT_AVAILABLE": { "summary": "INTERNAL_TRANSFERS_NOT_AVAILABLE (-11652)", "value": { "code": -11652, "message": "Internal transfers are currently not available." } } } } } } }, "security": [ { "apiKey": [], "apiSignature": [], "apiTimestamp": [] } ], "x-valr-permission": "TRANSFERS_CREATE", "x-valr-bundles": [ "TREASURY_WRITE" ], "x-valr-permissions": [ { "name": "TRANSFERS_CREATE", "bundles": [ "TREASURY_WRITE" ] } ], "x-valr-errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing.", "common": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked.", "common": true }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock.", "common": true }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once.", "common": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list.", "common": true }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint.", "common": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable.", "common": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "code": -11133, "name": "SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "httpStatus": 403, "message": "Internal transfer did not succeed", "reason": "The transfer was refused, and the message says why: `fromId` and `toId` are the same, one of them isn't an account in your business, the source account doesn't have enough available balance and `allowBorrow` is `false`, you called it on a sub-account and `fromId` isn't that sub-account, or your key is limited to sub-accounts and one of the accounts isn't among them." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currencyCode` isn't a currency VALR supports." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` is `true`, but the source account isn't enabled for margin." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "`allowBorrow` is `true`, but the source account doesn't have enough collateral to borrow the shortfall." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "Borrowing for transfers is temporarily unavailable. Transfer no more than the available balance, or try again later." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "This currency can't be borrowed for a transfer." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would take the source account past its borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would take the source account past its total borrow limit." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "Not enough of this currency is available to borrow right now. Try again later." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "The currency is under maintenance. Try again in a few minutes." }, { "ref": "ApplicationErrorCodes.INTERNAL_TRANSFERS_NOT_AVAILABLE", "code": -11652, "name": "INTERNAL_TRANSFERS_NOT_AVAILABLE", "httpStatus": 503, "message": "Internal transfers are currently not available.", "reason": "Transfers between accounts are temporarily unavailable." } ], "summary": "Transfer between accounts", "description": "Moves funds between two of your accounts: your primary account (`0`) and its sub-accounts. Called on your primary account it can move funds between any of them; called on a sub-account (with `X-VALR-SUB-ACCOUNT-ID`) it can only move funds out of that sub-account. A key limited to some sub-accounts can only move funds between those sub-accounts. The transfer is processed asynchronously: the 202 response means it was accepted, so check balances or transaction history to confirm it completed. The returned `id` appears as `additionalInfo.transferId` on the resulting `INTERNAL_TRANSFER` transactions.", "tags": [ "Sub-accounts" ] } }, "/v1/public/time": { "get": { "operationId": "getV1PublicTime", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTime" }, "example": { "epochTime": 1793004161, "time": "2026-10-26T08:42:41.280178906Z" } } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [], "summary": "Get the server time", "description": "Returns VALR's server time as Unix seconds (`epochTime`) and as an ISO 8601 timestamp (`time`). Signed requests are rejected when their timestamp is too far from the server's time, so use this to check your clock.", "tags": [ "Status and time" ] } }, "/v1/public/status": { "get": { "operationId": "getV1PublicStatus", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "online" } } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [], "summary": "Get the exchange status", "description": "Returns `online` when VALR accepts all requests, or `read-only` when it only accepts `GET` and `OPTIONS` requests and rejects the rest with `503`.", "tags": [ "Status and time" ] } }, "/v1/public/marketsummary": { "get": { "operationId": "getV1PublicMarketsummary", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1MarketSummaryRecordForApi" } }, "example": [ { "currencyPair": "BTCZAR", "askPrice": "1850012", "bidPrice": "1849800", "lastTradedPrice": "1849900", "previousClosePrice": "1832000", "baseVolume": "12.4518", "quoteVolume": "22958256.31", "highPrice": "1861000", "lowPrice": "1825500", "created": "2026-10-23T08:51:12.004Z", "changeFromPrevious": "0.98", "markPrice": "1849900" }, { "currencyPair": "BTCUSDTPERP", "askPrice": "105656", "bidPrice": "105594", "lastTradedPrice": "105611", "previousClosePrice": "106678", "baseVolume": "1.0638", "quoteVolume": "113947.8777", "highPrice": "108840", "lowPrice": "105600", "created": "2026-10-23T08:51:11.869Z", "changeFromPrevious": "-1", "markPrice": "105628" } ] } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [], "summary": "List market summaries", "description": "Returns the market summary of every currency pair: best ask and bid, last traded price, and the high, low and volume over the last 24 hours. `changeFromPrevious` is the percentage change from `previousClosePrice`, the last traded price before those 24 hours; responses are cached for up to 5 seconds.", "tags": [ "Market prices" ] } }, "/v1/public/{currencyPair}/marketsummary": { "get": { "operationId": "getV1PublicByCurrencyPairMarketsummary", "parameters": [ { "name": "currencyPair", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency pair symbol, e.g. `BTCZAR`.", "example": "BTCZAR" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1MarketSummaryRecordForApi" }, "example": { "currencyPair": "BTCZAR", "askPrice": "1850012", "bidPrice": "1849800", "lastTradedPrice": "1849900", "previousClosePrice": "1832000", "baseVolume": "12.4518", "quoteVolume": "22958256.31", "highPrice": "1861000", "lowPrice": "1825500", "created": "2026-10-23T08:51:12.004Z", "changeFromPrevious": "0.98", "markPrice": "1849900" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.INVALID_CURRENCY_PAIR": { "summary": "INVALID_CURRENCY_PAIR (-21)", "value": { "code": -21, "message": "Unsupported Currency Pair" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.MARKET_SUMMARY_NOT_FOUND": { "summary": "MARKET_SUMMARY_NOT_FOUND (-111)", "value": { "code": -111, "message": "Market summary not found" } } } } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [ { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "`currencyPair` isn't a currency pair VALR supports." }, { "ref": "ErrorCodes.MARKET_SUMMARY_NOT_FOUND", "code": -111, "name": "MARKET_SUMMARY_NOT_FOUND", "httpStatus": 404, "message": "Market summary not found", "reason": "VALR has no market summary for the pair yet, which can happen for a pair that isn't trading." } ], "summary": "Get a pair's market summary", "description": "Returns one currency pair's market summary: best ask and bid, last traded price, and the high, low and volume over the last 24 hours, with the percentage change from the last price before then. Responses are cached for up to 5 seconds.", "tags": [ "Market prices" ] } }, "/v1/public/{currencyPair}/buckets": { "get": { "operationId": "getV1PublicByCurrencyPairBuckets", "parameters": [ { "name": "currencyPair", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Currency pair symbol, e.g. `BTCZAR`.", "example": "BTCZAR" }, { "name": "periodSeconds", "in": "query", "required": false, "schema": { "type": "integer", "default": 60, "enum": [ 60, 300, 900, 1800, 3600, 21600, 86400 ] }, "description": "Length of each bucket in seconds: `60`, `300`, `900`, `1800`, `3600`, `21600` or `86400`.", "example": 60 }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only buckets that start at or after this time, as an ISO 8601 timestamp or Unix seconds. A value in neither format is ignored.", "example": "2026-10-23T00:00:00Z" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only buckets that start at or before this time, as an ISO 8601 timestamp or Unix seconds. A value in neither format is ignored.", "example": "2026-10-23T09:00:00Z" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of buckets to skip, for paging.", "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 300 }, "description": "Maximum number of buckets to return, up to 400.", "example": 300 }, { "name": "includeEmpty", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "`false` to leave out buckets with no trades.", "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BucketForDisplay" } }, "example": [ { "currencyPairSymbol": "BTCZAR", "bucketPeriodInSeconds": 60, "startTime": "2026-10-23T08:51:00Z", "open": "1849800", "high": "1850012", "low": "1849800", "close": "1849900", "volume": "0.0517", "quoteVolume": "95638.42" }, { "currencyPairSymbol": "BTCZAR", "bucketPeriodInSeconds": 60, "startTime": "2026-10-23T08:50:00Z", "open": "1849500", "high": "1849900", "low": "1849500", "close": "1849800", "volume": "0.2105", "quoteVolume": "389372.3" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.INVALID_CURRENCY_PAIR": { "summary": "INVALID_CURRENCY_PAIR (-21)", "value": { "code": -21, "message": "Unsupported Currency Pair" } }, "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [ { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "`currencyPair` isn't a currency pair VALR supports." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`periodSeconds` isn't one of the supported periods, `skip` or `limit` isn't a whole number, `limit` is more than 400, or `includeEmpty` isn't `true` or `false`." } ], "summary": "List price buckets", "description": "Returns the open, high, low and close prices and traded volume of a currency pair in buckets (candles) of `periodSeconds`, newest first. The current, unfinished bucket is included unless you skip results or `endTime` is in the past; responses are cached for up to 5 seconds.", "tags": [ "Market prices" ] } }, "/v1/public/currencies": { "get": { "operationId": "getV1PublicCurrencies", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1CurrencyForApi" } }, "example": [ { "symbol": "BTC", "isActive": true, "shortName": "BTC", "longName": "Bitcoin", "decimalPlaces": "8", "withdrawalDecimalPlaces": "8", "collateral": true, "collateralWeight": "0.95", "defaultNetworkType": "Bitcoin", "supportedNetworks": [ { "networkType": "Bitcoin", "networkLongName": "Bitcoin", "minimumWithdrawAmount": "0.0002", "estimatedSendCost": "0.000012", "deposit": true, "withdraw": true, "withdrawalDecimalPlaces": "8" } ] }, { "symbol": "USDC", "isActive": true, "shortName": "USDC", "longName": "USD Coin", "decimalPlaces": "2", "withdrawalDecimalPlaces": "6", "collateral": true, "collateralWeight": "1", "defaultNetworkType": "Ethereum", "supportedNetworks": [ { "networkType": "Ethereum", "networkLongName": "Ethereum", "tokenContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "minimumWithdrawAmount": "6.001789", "estimatedSendCost": "16", "deposit": true, "withdraw": true, "withdrawalDecimalPlaces": "6" }, { "networkType": "Solana", "networkLongName": "Solana", "tokenContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "minimumWithdrawAmount": "3.000594", "estimatedSendCost": "0.11", "deposit": true, "withdraw": true, "withdrawalDecimalPlaces": "6" } ] }, { "symbol": "R", "isActive": true, "shortName": "ZAR", "longName": "Rand", "decimalPlaces": "2", "withdrawalDecimalPlaces": "2", "collateral": true, "collateralWeight": "1" } ] } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [], "summary": "List currencies", "description": "Returns every currency VALR lists, including inactive ones, with its decimal places, collateral weight and, for crypto, the networks it can be deposited and withdrawn on (`shortName` is the code used in currency pairs, e.g. ZAR, whose `symbol` is `R`). Responses are cached for up to a minute, so `estimatedSendCost` may be out of date.", "tags": [ "Currencies and pairs" ] } }, "/v1/public/pairs": { "get": { "operationId": "getV1PublicPairs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1CurrencyPairForApi" } }, "example": [ { "symbol": "ETHZAR", "baseCurrency": "ETH", "quoteCurrency": "ZAR", "shortName": "ETH/ZAR", "active": true, "minBaseAmount": "0.0002", "maxBaseAmount": "69.21", "minQuoteAmount": "10", "maxQuoteAmount": "5000000", "tickSize": "1", "baseDecimalPlaces": "8", "marginTradingAllowed": true, "currencyPairType": "SPOT", "initialMarginFraction": "0.2", "maintenanceMarginFraction": "0.1", "autoCloseMarginFraction": "0.033333333" }, { "symbol": "BNBUSDC", "baseCurrency": "BNB", "quoteCurrency": "USDC", "shortName": "BNB/USDC", "active": true, "minBaseAmount": "0.0008", "maxBaseAmount": "80", "minQuoteAmount": "0.52", "maxQuoteAmount": "52000", "tickSize": "0.1", "baseDecimalPlaces": "4", "marginTradingAllowed": false, "currencyPairType": "SPOT" }, { "symbol": "BTCUSDTPERP", "baseCurrency": "BTC", "quoteCurrency": "USDT", "shortName": "BTC/USDTPERP", "active": true, "minBaseAmount": "0.0001", "maxBaseAmount": "7", "minQuoteAmount": "1", "maxQuoteAmount": "250000", "tickSize": "1", "baseDecimalPlaces": "4", "marginTradingAllowed": false, "currencyPairType": "FUTURE", "initialMarginFraction": "0.025", "maintenanceMarginFraction": "0.0125", "autoCloseMarginFraction": "0.0125" } ] } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [], "summary": "List currency pairs", "description": "Returns every currency pair VALR lists, including inactive ones, with its order size limits, tick size and type (`SPOT` or `FUTURE`); margin fractions are only included for margin and futures pairs. Responses are cached for up to a minute.", "tags": [ "Currencies and pairs" ] } }, "/v1/public/pairs/{type}": { "get": { "operationId": "getV1PublicPairsByType", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "SPOT", "FUTURE" ] }, "description": "`SPOT` or `FUTURE` (not case-sensitive).", "example": "FUTURE" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/V1CurrencyPairForApi" } }, "example": [ { "symbol": "BTCUSDTPERP", "baseCurrency": "BTC", "quoteCurrency": "USDT", "shortName": "BTC/USDTPERP", "active": true, "minBaseAmount": "0.0001", "maxBaseAmount": "7", "minQuoteAmount": "1", "maxQuoteAmount": "250000", "tickSize": "1", "baseDecimalPlaces": "4", "marginTradingAllowed": false, "currencyPairType": "FUTURE", "initialMarginFraction": "0.025", "maintenanceMarginFraction": "0.0125", "autoCloseMarginFraction": "0.0125" }, { "symbol": "ETHUSDTPERP", "baseCurrency": "ETH", "quoteCurrency": "USDT", "shortName": "ETH/USDTPERP", "active": true, "minBaseAmount": "0.001", "maxBaseAmount": "32", "minQuoteAmount": "1", "maxQuoteAmount": "100000", "tickSize": "0.1", "baseDecimalPlaces": "3", "marginTradingAllowed": false, "currencyPairType": "FUTURE", "initialMarginFraction": "0.025", "maintenanceMarginFraction": "0.0125", "autoCloseMarginFraction": "0.0125" } ] } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnErrorMessage" }, "examples": { "ErrorCodes.INVALID_REQUEST": { "summary": "INVALID_REQUEST (-11)", "value": { "code": -11, "message": "Invalid Request, please check your request and try again" } } } } } } }, "security": [], "x-valr-public": true, "x-valr-errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`type` isn't `SPOT` or `FUTURE`." } ], "summary": "List currency pairs by type", "description": "Returns the currency pairs of one type, spot or futures, including inactive ones, in the same form as List currency pairs. Responses are cached for up to a minute.", "tags": [ "Currencies and pairs" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-VALR-API-KEY", "description": "Your API key" }, "apiSignature": { "type": "apiKey", "in": "header", "name": "X-VALR-SIGNATURE", "description": "HMAC-SHA512 request signature" }, "apiTimestamp": { "type": "apiKey", "in": "header", "name": "X-VALR-TIMESTAMP", "description": "Request timestamp in milliseconds" } }, "schemas": { "V1AccountBalanceWithTotalForDisplay": { "type": "object", "properties": { "currency": { "type": "string" }, "available": { "type": "string" }, "reserved": { "type": "string" }, "total": { "type": "string" }, "updatedAt": { "type": "string" }, "lendReserved": { "type": "string" }, "borrowReserved": { "type": "string" }, "borrowedAmount": { "type": "string" }, "totalInReference": { "type": "string" }, "totalInReferenceWeighted": { "type": "string" }, "referenceCurrency": { "type": "string" } }, "required": [ "currency", "available", "reserved", "total", "lendReserved", "borrowReserved", "borrowedAmount", "totalInReference", "totalInReferenceWeighted", "referenceCurrency" ] }, "V1APIUserTransactionRecord": { "type": "object", "properties": { "transactionType": { "$ref": "#/components/schemas/UserTransactionTypeForDisplay", "description": "What kind of transaction this is." }, "debitCurrency": { "type": "string", "description": "Currency taken from the account. Absent if nothing was taken." }, "debitValue": { "type": "string", "description": "Amount taken from the account." }, "creditCurrency": { "type": "string", "description": "Currency added to the account. Absent if nothing was added." }, "creditValue": { "type": "string", "description": "Amount added to the account." }, "feeCurrency": { "type": "string", "description": "Currency of the fee. Absent if there was no fee." }, "feeValue": { "type": "string", "description": "Fee charged." }, "eventAt": { "type": "string", "description": "When the transaction happened, as an ISO 8601 timestamp in UTC." }, "id": { "type": "string", "format": "uuid", "description": "Transaction ID. In List transactions, pass it as `beforeId` to fetch older transactions." }, "additionalInfo": { "type": "object", "additionalProperties": true, "description": "Details that depend on `transactionType`. For example, trades carry `currencyPairSymbol`, `orderId` and the price as `costPerCoin` in `costPerCoinSymbol`; transfers between your accounts carry `reason`, `reasonDescription`, `additional` (which accounts were involved) and `transferId`, the `id` returned by Transfer between accounts. Absent when there are no details." } }, "required": [ "transactionType", "eventAt", "id" ] }, "UserTransactionTypeForDisplay": { "type": "object", "properties": { "type": { "type": "string", "description": "Transaction type, e.g. `LIMIT_BUY`, `FIAT_DEPOSIT` or `INTERNAL_TRANSFER`. Use these values in `transactionTypes`." }, "description": { "type": "string", "description": "Readable name of the type." } }, "required": [ "type", "description" ] }, "V1APISubAccountUserTransactions": { "type": "object", "properties": { "id": { "type": "string", "description": "Sub-account ID." }, "label": { "type": "string", "description": "Sub-account name." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/V1APIUserTransactionRecord" }, "description": "The sub-account's matching transactions, newest first." } }, "required": [ "id", "label", "transactions" ] }, "ReturnErrorMessage": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "validationErrors": { "$ref": "#/components/schemas/ValidationErrors" } }, "required": [ "message" ] }, "ValidationErrors": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } }, "required": [ "errors" ] }, "ValidationError": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] }, "BucketForDisplay": { "type": "object", "properties": { "currencyPairSymbol": { "type": "string" }, "bucketPeriodInSeconds": { "type": "integer", "format": "int32" }, "startTime": { "type": "string" }, "open": { "type": "string" }, "high": { "type": "string" }, "low": { "type": "string" }, "close": { "type": "string" }, "volume": { "type": "string" }, "quoteVolume": { "type": "string" } }, "required": [ "currencyPairSymbol", "startTime", "open", "high", "low", "close", "volume", "quoteVolume" ] }, "IncomingUniqueDepositReferenceRequest": { "type": "object", "properties": { "expectedAmount": { "type": "string", "nullable": true, "description": "Amount you expect the payer to deposit, as a decimal string greater than zero." }, "name": { "type": "string", "maxLength": 64, "pattern": "^\\p{Z}*[\\p{L}\\d'’]+[\\p{L}\\p{Z}\\d'’\\-&.(),+]*$", "nullable": true, "description": "Payer's name." }, "email": { "type": "string", "maxLength": 64, "pattern": "^(?=.{6,128}$)[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,63}$", "x-pattern-flags": [ "CASE_INSENSITIVE" ], "nullable": true, "description": "Payer's email address." } } }, "IncomingCreateWebhookSubscriptionRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "HTTPS URL to deliver events to, up to 2,048 characters. It must resolve to a public IP address and mustn't contain a username or password. Redirects aren't followed." }, "eventTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "Event types to send, from 1 to 20 `name` values returned by `GET /v1/webhooks/event-types`." }, "description": { "type": "string", "maxLength": 256, "pattern": "^[\\pL\\pZ\\pP\\d\\r\\n.+]{0,}$", "nullable": true, "description": "Your label for the webhook, up to 256 characters of letters, digits, spaces and punctuation." } }, "required": [ "url", "eventTypes" ] }, "IncomingUpdateWebhookSubscriptionRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "nullable": true, "description": "New HTTPS URL, under the same rules as when creating a webhook. Leave out to keep the current URL." }, "eventTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "nullable": true, "description": "Replaces the webhook's event types, from 1 to 20 `name` values. Leave out to keep the current ones." }, "active": { "type": "boolean", "nullable": true, "description": "`false` pauses deliveries and `true` resumes them. Leave out to keep the current state." }, "description": { "type": "string", "maxLength": 256, "pattern": "^[\\pL\\pZ\\pP\\d\\r\\n.+]{0,}$", "nullable": true, "description": "New label for the webhook, up to 256 characters of letters, digits, spaces and punctuation. Leave out to keep the current one." } } }, "BulkDepositReferenceRequest": { "type": "object", "properties": { "senders": { "type": "array", "items": { "$ref": "#/components/schemas/BulkSenderInput" }, "description": "Payers to create references for, one reference each." } }, "required": [ "senders" ] }, "BulkSenderInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64, "description": "Payer's name." }, "email": { "type": "string", "description": "Payer's email address." }, "expectedAmount": { "type": "string", "nullable": true, "description": "Amount you expect the payer to deposit, as a decimal string greater than zero." } }, "required": [ "name", "email" ] }, "IncomingDepositReferenceLinkRequest": { "type": "object", "properties": { "referenceCode": { "type": "string", "pattern": "^VPAY-[A-HJ-NP-Z2-9]{7}$", "description": "The reference to link the deposit to." } }, "required": [ "referenceCode" ] }, "V1SendCryptoRequest": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount to send, in the currency in the path, as a decimal string greater than zero. Decimal places beyond the network's `withdrawalDecimalPlaces` are rounded down." }, "addressBookId": { "type": "string", "nullable": true, "description": "ID of an entry in the account's address book, from `GET /v1/wallet/crypto/address-book`. Send either this or `address`, not both; the entry's network and payment reference are used." }, "address": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9:.]+$", "nullable": true, "description": "Destination address. Send either this or `addressBookId`, not both." }, "networkType": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z]+$", "nullable": true, "description": "Network to send on, e.g. `Ethereum`; defaults to the currency's default network. Make sure it matches the address: sending on the wrong network can lose the funds. Ignored with `addressBookId`." }, "paymentReference": { "type": "string", "minLength": 1, "maxLength": 256, "nullable": true, "description": "Memo, tag or payment reference, for networks that use one; up to 256 characters. Ignored with `addressBookId`." }, "allowBorrow": { "type": "boolean", "nullable": true, "description": "Borrow against the account's other assets to cover a shortfall. Only for margin-enabled accounts; defaults to `false`." }, "beneficiaryName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\p{L}\\d'’]+[\\p{L}\\p{Z}\\d'’\\-&.(),+]*$", "nullable": true, "description": "Recipient's full name. Required, with `isCorporate` and `isSelfHosted`, unless the address belongs to a VALR account or the address-book entry already holds the recipient's details." }, "isCorporate": { "type": "boolean", "nullable": true, "description": "`true` if the recipient is a business, `false` if a person." }, "isSelfHosted": { "type": "boolean", "nullable": true, "description": "`true` if the recipient holds their own keys, `false` if an exchange or other provider hosts the address. When `false`, also send `serviceProviderId` or `serviceProviderName`." }, "serviceProviderName": { "type": "string", "maxLength": 256, "pattern": "^[\\p{L}\\d'’]+[\\p{L}\\p{Z}\\d'’\\-&.(),+]*$", "nullable": true, "description": "Name of the recipient's provider, if it isn't in the service-providers list. Send this or `serviceProviderId`, not both." }, "serviceProviderId": { "type": "string", "maxLength": 256, "pattern": "^[a-zA-Z0-9 ]+$", "nullable": true, "description": "ID of the recipient's provider, from `GET /v1/wallet/crypto/service-providers`. Send this or `serviceProviderName`, not both." } }, "required": [ "amount" ] }, "IncomingLinkedBankAccount": { "type": "object", "properties": { "bank": { "type": "string", "minLength": 1, "maxLength": 32 }, "accountHolder": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z0-9\\s.'_\\-(),&/]*$" }, "accountNumber": { "type": "string", "minLength": 1, "pattern": "^[0-9]*$" }, "branchCode": { "type": "string", "minLength": 1, "nullable": true }, "suppliedBankCode": { "type": "string", "nullable": true }, "accountType": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "markForAutoPayout": { "type": "boolean", "nullable": true }, "tradingName": { "type": "string", "pattern": "^[a-zA-Z0-9\\s.,'_\\-/&()]{1,64}$", "nullable": true }, "countryOfRegistration": { "type": "string", "pattern": "^[A-Za-z]{2}$", "nullable": true } }, "required": [ "bank", "accountHolder", "accountNumber", "branchCode", "accountType" ] }, "V1IncomingNewFiatWithdrawal": { "type": "object", "properties": { "linkedBankAccountId": { "type": "string" }, "amount": { "type": "string" }, "fast": { "type": "boolean", "nullable": true }, "instant": { "type": "boolean", "nullable": true }, "allowBorrow": { "type": "boolean", "nullable": true }, "reference": { "type": "string", "minLength": 1, "maxLength": 35, "pattern": "^[A-Za-z0-9 /'-]+$", "nullable": true } }, "required": [ "linkedBankAccountId", "amount" ] }, "IncomingPaymentFiat": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,9}$", "x-pattern-flags": [ "CASE_INSENSITIVE" ], "nullable": true }, "beneficiaryId": { "type": "string", "nullable": true }, "newBeneficiary": { "allOf": [ { "$ref": "#/components/schemas/IncomingLinkedBankAccount" } ], "nullable": true }, "fast": { "type": "boolean", "nullable": true }, "reference": { "type": "string", "minLength": 1, "maxLength": 35, "pattern": "^[A-Za-z0-9 /'-]+$", "nullable": true } }, "required": [ "amount" ] }, "IncomingPaymentCrypto": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,9}$", "x-pattern-flags": [ "CASE_INSENSITIVE" ], "nullable": true }, "beneficiaryId": { "type": "string", "nullable": true }, "newBeneficiary": { "allOf": [ { "$ref": "#/components/schemas/IncomingAddressBookEntryAddRequestWithOptionalBeneficiaryInfo" } ], "nullable": true }, "fee": { "type": "string", "nullable": true }, "feePriority": { "type": "string", "minLength": 1, "maxLength": 32, "nullable": true }, "allowBorrow": { "type": "boolean", "nullable": true } }, "required": [ "amount" ] }, "IncomingAddressBookEntryAddRequestWithOptionalBeneficiaryInfo": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9 -]*$" }, "currency": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,9}$", "nullable": true }, "address": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9:.]+$" }, "paymentReference": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[a-zA-Z0-9:]+$" }, "networkType": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z]+$" }, "beneficiaryName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\p{L}\\d'’]+[\\p{L}\\p{Z}\\d'’\\-&.(),+]*$", "nullable": true }, "isCorporate": { "type": "boolean", "nullable": true }, "isSelfHosted": { "type": "boolean", "nullable": true }, "serviceProviderName": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\p{L}\\d'’]+[\\p{L}\\p{Z}\\d'’\\-&.(),+]*$", "nullable": true }, "serviceProviderId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[a-zA-Z0-9 ]+$", "nullable": true } }, "required": [ "label", "address", "paymentReference", "networkType" ] }, "V1IncomingSubAccountRegisterRequest": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9 -]*$", "description": "Name for the sub-account: 1 to 64 letters, digits, spaces or hyphens. It must differ from your other sub-accounts' names, ignoring case, and can't be `Primary` or `Main`." }, "accountTags": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Tags to set on the new sub-account. The only tag you can set is `CLIENT_FUNDS`, which marks it as an account for your clients' funds; values VALR doesn't recognise are ignored." } }, "required": [ "label" ] }, "V1IncomingUpdateSubAccountRequest": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "minimum": 0, "exclusiveMinimum": true, "description": "ID of the sub-account to rename. You can also send it as a string, which avoids losing precision in languages whose numbers are 64-bit floats." }, "label": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9 -]*$", "description": "New name, under the same rules as when creating a sub-account. Sending the current name changes nothing." } }, "required": [ "id", "label" ] }, "V1IncomingDeactivateSubAccountRequest": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "minimum": 0, "exclusiveMinimum": true, "description": "ID of the sub-account to delete. You can also send it as a string, which avoids losing precision in languages whose numbers are 64-bit floats." } }, "required": [ "id" ] }, "V1IncomingSubAccountInternalTransferRequest": { "type": "object", "properties": { "fromId": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "description": "ID of the account to transfer from: `0` for your primary account, or a sub-account's `id`. You can also send it as a string." }, "toId": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "description": "ID of the account to transfer to, in the same form as `fromId`." }, "currencyCode": { "type": "string", "pattern": "^[A-Z0-9]{1,9}$", "minLength": 1, "description": "Currency to transfer, in upper case, e.g. `USDC`." }, "amount": { "type": "string", "description": "Amount to transfer, as a decimal string greater than zero of up to 32 characters." }, "allowBorrow": { "type": "boolean", "description": "`true` to borrow any shortfall against the source account's collateral, if that account is enabled for margin. Defaults to `false` if left out." } }, "required": [ "fromId", "toId", "currencyCode", "amount", "allowBorrow" ] }, "UniqueDepositReferenceForDisplay": { "type": "object", "properties": { "referenceCode": { "type": "string", "description": "The reference your payer quotes when depositing." }, "currency": { "type": "string" }, "expectedAmount": { "type": "string" }, "createdAt": { "type": "integer", "format": "int64", "description": "When the reference was created, in Unix milliseconds." }, "name": { "type": "string" }, "email": { "type": "string" }, "matchedDeposits": { "type": "array", "items": { "$ref": "#/components/schemas/UserMatchedDepositInfo" }, "description": "Deposits matched to this reference." }, "matchedDepositCount": { "type": "integer", "format": "int32" } }, "required": [ "referenceCode", "currency", "createdAt", "matchedDeposits", "matchedDepositCount" ] }, "UserMatchedDepositInfo": { "type": "object", "properties": { "publicId": { "type": "string", "format": "uuid" }, "amount": { "type": "string" }, "effectiveDate": { "type": "string" }, "creditedAt": { "type": "integer", "format": "int64" }, "isOverride": { "type": "boolean", "description": "`true` if this deposit is set as the reference's override deposit." } }, "required": [ "publicId", "amount", "effectiveDate", "creditedAt", "isOverride" ] }, "WebhookSubscriptionForDisplay": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Webhook ID." }, "scopeKind": { "type": "string", "description": "What the webhook is attached to. Always `ENTITY` for webhooks managed with an institution key: the webhook receives events for every account in your business." }, "scopeLabel": { "type": "string", "description": "Readable label for `scopeKind`." }, "url": { "type": "string", "description": "URL events are delivered to." }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Event types delivered to this webhook." }, "active": { "type": "boolean", "description": "Whether events are delivered. An inactive webhook receives nothing until it's reactivated." }, "description": { "type": "string", "description": "Your label for the webhook. Absent if you didn't set one." }, "signingSecretFingerprint": { "type": "string", "description": "First 8 hex characters of the SHA-256 hash of the signing secret, so you can check which secret the webhook uses. The secret itself is only returned when the webhook is created." }, "createdAt": { "type": "string", "description": "When the webhook was created, as an ISO 8601 timestamp in UTC." }, "updatedAt": { "type": "string", "description": "When the webhook was last changed, as an ISO 8601 timestamp in UTC." } }, "required": [ "identifier", "scopeKind", "scopeLabel", "url", "eventTypes", "active", "signingSecretFingerprint", "createdAt", "updatedAt" ] }, "WebhookSubscriptionCreatedForDisplay": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionForDisplay", "description": "The new webhook." }, "signingSecret": { "type": "string", "description": "Secret for verifying deliveries. It's shown only in this response and can't be retrieved later, so store it securely." } }, "required": [ "subscription", "signingSecret" ] }, "WebhookDeliveriesPageForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttemptForDisplay" }, "description": "Delivery attempts on this page, newest first." }, "total": { "type": "integer", "format": "int32", "description": "Number of attempts across all pages." }, "limit": { "type": "integer", "format": "int32", "description": "The `limit` used for this page." }, "offset": { "type": "integer", "format": "int32", "description": "The `skip` used for this page." } }, "required": [ "items", "total", "limit", "offset" ] }, "WebhookDeliveryAttemptForDisplay": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Event ID. The same for every attempt to deliver an event, and sent in the `Valr-Webhook-Event-Id` header." }, "eventType": { "type": "string", "description": "Event type, as sent in the `Valr-Webhook-Event-Type` header." }, "attemptNumber": { "type": "integer", "format": "int32", "description": "1 for the first attempt, increasing by one with each retry." }, "responseStatus": { "type": "integer", "format": "int32", "description": "HTTP status your endpoint returned. Absent if no response was received." }, "errorCategory": { "type": "string", "description": "Why the attempt failed: `TIMEOUT`, `CONNECTION_REFUSED`, `CONNECTION_RESET`, `DNS_FAILURE`, `TLS_FAILURE`, `NETWORK_UNREACHABLE`, `HTTP_STATUS`, `BLOCKED` or `UNKNOWN`. Absent if the attempt succeeded." }, "errorMessage": { "type": "string", "description": "Readable explanation of `errorCategory`." }, "nextRetryAt": { "type": "string", "description": "When the event will be retried, as an ISO 8601 timestamp in UTC. Absent if this attempt won't be retried." }, "terminalState": { "type": "string", "description": "Set on the last attempt for an event: `SUCCESS`, `PERMANENT_FAILURE` (the failure isn't retried, for example a 4xx response) or `DEAD_LETTER` (every retry failed). Absent while delivery is still being retried." }, "createdAt": { "type": "string", "description": "When the attempt was made, as an ISO 8601 timestamp in UTC." } }, "required": [ "eventId", "eventType", "attemptNumber", "createdAt" ] }, "WebhookEventForDisplay": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Event ID." }, "eventType": { "type": "string", "description": "Event type." }, "payload": { "type": "string", "description": "The exact JSON body that was delivered, as a string. Retries send the same body." }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttemptForDisplay" }, "description": "Every attempt to deliver this event, oldest first." } }, "required": [ "eventId", "eventType", "payload", "attempts" ] }, "WebhookEventTypeForDisplay": { "type": "object", "properties": { "name": { "type": "string", "description": "Value to use in a webhook's `eventTypes`." }, "displayName": { "type": "string", "description": "Short readable label." }, "description": { "type": "string", "description": "What triggers the event. Absent for some event types." } }, "required": [ "name", "displayName" ] }, "BulkDepositJobResponse": { "type": "object", "properties": { "jobId": { "type": "integer", "format": "int64", "description": "ID of the job. Use it to check the job's status and read its items." }, "totalItems": { "type": "integer", "format": "int32" }, "acceptedItems": { "type": "integer", "format": "int32", "description": "Number of payers accepted into the job." } }, "required": [ "jobId", "totalItems", "acceptedItems" ] }, "BulkDepositJobStatusResponse": { "type": "object", "properties": { "jobId": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/BulkDepositJobStatus", "description": "`PROCESSING` while references are being created, then `COMPLETED` if every reference was created or `PARTIALLY_FAILED` if any failed." }, "totalItems": { "type": "integer", "format": "int32" }, "acceptedItems": { "type": "integer", "format": "int32" }, "completedItems": { "type": "integer", "format": "int32", "description": "Number of references created. Filled in when the job finishes." }, "failedItems": { "type": "integer", "format": "int32", "description": "Number of payers whose reference couldn't be created. Filled in when the job finishes." }, "createdAt": { "type": "string", "description": "When the job was created, in Unix milliseconds." }, "completedAt": { "type": "string", "description": "When the job finished, in Unix milliseconds. Absent until the job finishes." } }, "required": [ "jobId", "status", "totalItems", "acceptedItems", "completedItems", "failedItems", "createdAt" ] }, "BulkDepositJobStatus": { "type": "string", "enum": [ "PROCESSING", "COMPLETED", "PARTIALLY_FAILED" ] }, "BulkDepositItemsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BulkDepositItemForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "BulkDepositItemForDisplay": { "type": "object", "properties": { "senderIndex": { "type": "integer", "format": "int32", "description": "Position of the payer in the submitted `senders` array, starting at 0." }, "currency": { "$ref": "#/components/schemas/CurrencyForDisplay", "description": "Currency code, e.g. `ZAR`." }, "expectedAmount": { "type": "number", "description": "Amount you expect the payer to deposit, as a decimal string. Absent if you didn't give one." }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "$ref": "#/components/schemas/BulkDepositItemStatus", "description": "`PENDING` until the payer has been processed, then `SUCCESS` or `FAILED`." }, "referenceCode": { "type": "string", "description": "The reference created for this payer, once `status` is `SUCCESS`." }, "errorCode": { "type": "integer", "format": "int32", "description": "Why the reference couldn't be created, when `status` is `FAILED`: `-15116` daily limit reached, `-15119` maximum number of references reached, `-15113` any other failure." }, "processedAt": { "type": "integer", "format": "int64", "description": "When the payer was processed, in Unix milliseconds." } }, "required": [ "senderIndex", "currency", "name", "email", "status" ] }, "CurrencyForDisplay": { "type": "object", "properties": { "symbol": { "type": "string" }, "decimalPlaces": { "type": "integer", "format": "int32" }, "isActive": { "type": "boolean" }, "shortName": { "type": "string" }, "longName": { "type": "string" }, "supportedWithdrawDecimalPlaces": { "type": "integer", "format": "int32" }, "paymentReferenceFieldName": { "type": "string" }, "collateral": { "type": "boolean" }, "collateralWeight": { "type": "string" }, "supportedNetworks": { "type": "array", "items": { "$ref": "#/components/schemas/SupportedNetworkForDisplay" } }, "currencyTypeId": { "type": "integer", "format": "int32" } }, "required": [ "symbol", "decimalPlaces", "isActive", "shortName", "longName", "supportedWithdrawDecimalPlaces", "collateral", "collateralWeight" ] }, "SupportedNetworkForDisplay": { "type": "object", "properties": { "networkType": { "type": "string" }, "networkLongName": { "type": "string" }, "tokenContract": { "type": "string" }, "minimumWithdrawAmount": { "type": "string" }, "estimatedSendCost": { "type": "string" }, "deposit": { "type": "boolean" }, "withdraw": { "type": "boolean" }, "withdrawalDecimalPlaces": { "type": "integer", "format": "int32" } }, "required": [ "networkType", "deposit", "withdraw" ] }, "BulkDepositItemStatus": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED" ] }, "UserFiatDepositsSearchResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserFiatDepositForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "UserFiatDepositForDisplay": { "type": "object", "properties": { "publicId": { "type": "string", "format": "uuid", "description": "Deposit ID. Use it to link the deposit to a reference." }, "amount": { "type": "string" }, "effectiveDate": { "type": "string", "description": "The deposit's effective date at the bank, as `YYYY-MM-DD`." }, "creditedAt": { "type": "integer", "format": "int64", "description": "When the deposit was recorded, in Unix milliseconds." }, "linkedReferenceCode": { "type": "string", "description": "The reference this deposit is linked to, if any." } }, "required": [ "publicId", "amount", "effectiveDate", "creditedAt" ] }, "UniqueDepositReferenceSearchResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UniqueDepositReferenceForDisplay" } }, "total": { "type": "integer", "format": "int32", "description": "Total number of matching references across all pages." }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "description": "`true` when a search had too many candidates to check them all. Narrow your search to be sure of finding the reference." } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "V1FundAddress": { "type": "object", "properties": { "currency": { "type": "string" }, "address": { "type": "string" }, "networkType": { "type": "string" }, "paymentReference": { "type": "string", "description": "Memo, tag or reference that deposits to this address must include, on networks that use one." }, "legacy": { "type": "boolean", "description": "`true` if this is an older address that still works; left out otherwise." } }, "required": [ "currency", "address", "networkType" ] }, "V1BlockchainReceiveTransactionForApi": { "type": "object", "properties": { "currencyCode": { "type": "string" }, "networkType": { "type": "string", "description": "Network the deposit arrived on. Left out for some older deposits." }, "receiveAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "amount": { "type": "string" }, "createdAt": { "type": "string", "description": "When the deposit was detected. `startTime` and `endTime` filter on this." }, "confirmations": { "type": "integer", "format": "int32" }, "confirmed": { "type": "boolean" }, "confirmedAt": { "type": "string", "description": "When the deposit was confirmed; left out until then." } }, "required": [ "currencyCode", "receiveAddress", "transactionHash", "amount", "createdAt", "confirmations", "confirmed" ] }, "V1WithdrawDetailsForApi": { "type": "object", "properties": { "currency": { "type": "string" }, "minimumWithdrawAmount": { "type": "string" }, "withdrawalDecimalPlaces": { "type": "string", "description": "Most decimal places a withdrawal amount can have; extra places are rounded down." }, "isActive": { "type": "boolean", "description": "Whether withdrawals of this currency on this network are open." }, "withdrawCost": { "type": "string", "description": "Network fee charged on top of each withdrawal, in this currency." }, "networkType": { "type": "string" }, "supportsPaymentReference": { "type": "boolean", "description": "Whether withdrawals on this network can carry a `paymentReference`." }, "paymentReferenceFieldName": { "type": "string", "description": "What this network calls its payment reference, when it supports one." } }, "required": [ "currency", "minimumWithdrawAmount", "withdrawalDecimalPlaces", "isActive", "withdrawCost", "networkType", "supportsPaymentReference" ] }, "V1BlockchainSendTransactionForApi": { "type": "object", "properties": { "currency": { "type": "string" }, "address": { "type": "string" }, "amount": { "type": "string" }, "feeAmount": { "type": "string", "description": "Network fee, charged on top of `amount`." }, "transactionHash": { "type": "string", "description": "Network transaction hash, once the withdrawal has been broadcast." }, "confirmations": { "type": "integer", "format": "int32" }, "lastConfirmationAt": { "type": "string", "description": "Time of the latest network confirmation, in UTC but without a time-zone designator." }, "uniqueId": { "type": "string", "format": "uuid", "description": "Withdrawal ID." }, "createdAt": { "type": "string", "description": "When the withdrawal was created. `startTime` and `endTime` filter on this." }, "verified": { "type": "boolean" }, "status": { "type": "string", "description": "`Pending`, `Awaiting approval`, `Processing`, `Complete`, `Failed` or `Cancelled`. Withdrawal lists leave out cancelled withdrawals." }, "networkType": { "type": "string" }, "paymentReference": { "type": "string" }, "paymentReferenceFieldName": { "type": "string" } }, "required": [ "currency", "address", "amount", "feeAmount", "confirmations", "uniqueId", "createdAt", "verified", "status" ] }, "V1WithdrawLimitDetailsForApi": { "type": "object", "properties": { "limitType": { "type": "string", "description": "`daily` for a limit over the last 24 hours, or `lifetime` for a limit over the life of the account." }, "totalWithdrawnAmountInReferenceCurrency": { "type": "string", "description": "Amount withdrawn in the limit's period, valued in `referenceCurrency`." }, "withdrawLimitAmountInReferenceCurrency": { "type": "string", "description": "The limit, in `referenceCurrency`." }, "referenceCurrency": { "type": "string" }, "maxWithdrawAmountInWithdrawCurrency": { "type": "string", "description": "Most you can still withdraw in the period, in `withdrawCurrency`." }, "withdrawCurrency": { "type": "string" } }, "required": [ "limitType", "totalWithdrawnAmountInReferenceCurrency", "withdrawLimitAmountInReferenceCurrency", "referenceCurrency", "maxWithdrawAmountInWithdrawCurrency", "withdrawCurrency" ] }, "V1AddressBookEntryForApi": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Entry ID; send it as `addressBookId` to withdraw to this address." }, "label": { "type": "string" }, "currency": { "type": "string", "description": "Currency of a `CURRENCY_SPECIFIC` entry; left out for `UNIVERSAL` entries." }, "address": { "type": "string" }, "networkType": { "type": "string" }, "paymentReference": { "type": "string" }, "createdAt": { "type": "string" }, "type": { "$ref": "#/components/schemas/AddressBookEntryTypeForDisplay", "description": "`CURRENCY_SPECIFIC`: one currency on one network. `UNIVERSAL`: any currency on the entry's network." }, "beneficiaryName": { "type": "string", "description": "Recipient's name saved with the entry. When the entry holds the recipient's details, withdrawals to it don't need them in the request." }, "isCorporate": { "type": "boolean" }, "isSelfHosted": { "type": "boolean" }, "serviceProviderName": { "type": "string" }, "serviceProviderId": { "type": "string" } }, "required": [ "id", "label", "address", "networkType", "createdAt", "type" ] }, "AddressBookEntryTypeForDisplay": { "type": "string", "enum": [ "CURRENCY_SPECIFIC", "UNIVERSAL" ] }, "VaspItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider ID; send it as `serviceProviderId` when withdrawing." }, "name": { "type": "string" }, "hidden": { "type": "boolean" } }, "required": [ "id", "name", "hidden" ] }, "V1LinkedBankAccountForApi": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bank": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "createdAt": { "type": "string" }, "country": { "type": "string" } }, "required": [ "id", "bank", "accountHolder", "accountNumber", "branchCode", "accountType", "createdAt", "country" ] }, "V1LinkedBankAccountForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bankCode": { "type": "string" }, "bankName": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "status": { "$ref": "#/components/schemas/LinkedBankAccountStatus" }, "insertedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "country": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyForDisplay" } }, "required": [ "id", "bankCode", "bankName", "accountHolder", "accountNumber", "branchCode", "accountType", "status", "insertedAt", "updatedAt", "country", "currency" ] }, "LinkedBankAccountStatus": { "type": "string", "enum": [ "NEW", "CONFIRMED", "DELETED", "VERIFIED", "VERIFICATION_FAILED" ] }, "BankForDisplay": { "type": "object", "properties": { "code": { "type": "string" }, "displayName": { "type": "string" }, "defaultBranchCode": { "type": "string" }, "rtcParticipant": { "type": "boolean" }, "rtgsParticipant": { "type": "boolean" }, "countryCode": { "$ref": "#/components/schemas/CountryCode" }, "deprecated": { "type": "string" } }, "required": [ "code", "displayName", "defaultBranchCode", "rtcParticipant", "rtgsParticipant", "countryCode" ] }, "CountryCode": { "type": "string", "enum": [ "UNDEFINED", "AC", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BU", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CP", "CR", "CS", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DG", "DJ", "DK", "DM", "DO", "DZ", "EA", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "EU", "EZ", "FI", "FJ", "FK", "FM", "FO", "FR", "FX", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "IC", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NT", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SF", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SU", "SV", "SX", "SY", "SZ", "TA", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TP", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UK", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XI", "XU", "XK", "YE", "YT", "YU", "ZA", "ZM", "ZR", "ZW" ] }, "AccountDepositReferenceForDisplay": { "type": "object", "properties": { "reference": { "type": "string" } }, "required": [ "reference" ] }, "FiatWithdrawalFeeEstimateForDisplay": { "type": "object", "properties": { "feeAmount": { "type": "string" }, "fullAmount": { "type": "string" }, "fast": { "type": "boolean" } }, "required": [ "feeAmount", "fullAmount", "fast" ] }, "FiatWithdrawalPageForV1Display": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FiatWithdrawalForV1Display" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "FiatWithdrawalForV1Display": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subAccountId": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "status": { "$ref": "#/components/schemas/SimplifiedFiatWithdrawalStatus" }, "linkedBankAccountId": { "type": "string", "format": "uuid" }, "isFast": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "feeAmount": { "type": "string" }, "failureReason": { "type": "string" }, "failureReasonDescription": { "type": "string" }, "failureReasonAction": { "type": "string" }, "failureRetryable": { "type": "boolean" } }, "required": [ "id", "subAccountId", "currency", "amount", "status", "linkedBankAccountId", "isFast", "createdAt", "updatedAt" ] }, "SimplifiedFiatWithdrawalStatus": { "type": "string", "enum": [ "NEW", "PENDING_APPROVAL", "PROCESSING", "PAID", "REVERSED", "FAILED", "DECLINED" ] }, "FiatWithdrawalDetailForV1Display": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subAccountId": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "status": { "$ref": "#/components/schemas/SimplifiedFiatWithdrawalStatus" }, "isFast": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "linkedBankAccount": { "$ref": "#/components/schemas/V1LinkedBankAccountForDisplay" }, "reference": { "type": "string" }, "feeAmount": { "type": "string" }, "reversal": { "$ref": "#/components/schemas/FiatWithdrawalReversalForDisplay" }, "failureReason": { "type": "string" }, "failureReasonDescription": { "type": "string" }, "failureReasonAction": { "type": "string" }, "failureRetryable": { "type": "boolean" } }, "required": [ "id", "subAccountId", "currency", "amount", "status", "isFast", "createdAt", "updatedAt", "linkedBankAccount" ] }, "FiatWithdrawalReversalForDisplay": { "type": "object", "properties": { "principalReturned": { "type": "string" }, "feeReturned": { "type": "string" }, "returnedAt": { "type": "string" } }, "required": [ "principalReturned", "returnedAt" ] }, "V1AccountCurrencyBalancesForApi": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/V1SubAccountForApi", "description": "The account. `id` `0` is your primary account." }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/V1CurrencyBalanceForApi" }, "description": "Each currency in the account with a balance, reserved amount or debt. Empty if there are none." } }, "required": [ "account", "balances" ] }, "V1SubAccountForApi": { "type": "object", "properties": { "label": { "type": "string", "description": "Account name. Your primary account's is `Primary`." }, "id": { "type": "string", "description": "Account ID: `0` for your primary account. It's a string because sub-account IDs can be larger than some languages' numbers hold exactly. Send a sub-account's ID in `X-VALR-SUB-ACCOUNT-ID` to act on it." }, "accountTags": { "type": "array", "items": { "type": "string" }, "description": "Tags on the account, such as `CLIENT_FUNDS`. Only returned when you set `includeTags` to `true`." }, "autoPayoutLinkedBankAccountId": { "type": "string", "description": "ID of the bank account this account pays out to automatically. Only returned when you set `includePayoutAccounts` to `true` and the account has one." } }, "required": [ "label", "id" ] }, "V1CurrencyBalanceForApi": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code, e.g. `ZAR`." }, "available": { "type": "string", "description": "Amount available to trade, transfer or withdraw." }, "reserved": { "type": "string", "description": "Amount reserved for open orders and pending withdrawals." }, "total": { "type": "string", "description": "`available` plus `reserved`, `lendReserved` and `borrowReserved`, minus `borrowedAmount`. Negative if the account owes more of this currency than it holds." }, "updatedAt": { "type": "string", "description": "When the balance last changed, as an ISO 8601 timestamp in UTC." }, "lendReserved": { "type": "string", "description": "Amount committed to lending." }, "borrowReserved": { "type": "string", "description": "Amount held as collateral for borrowing." }, "borrowedAmount": { "type": "string", "description": "Amount borrowed and not yet repaid." } }, "required": [ "currency", "available", "reserved", "total", "lendReserved", "borrowReserved", "borrowedAmount" ] }, "V1SubAccountWithKycForApi": { "type": "object", "properties": { "id": { "type": "string", "description": "Sub-account ID." }, "label": { "type": "string", "description": "Sub-account name." }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dateOfBirth": { "type": "string" }, "residentialCountry": { "type": "string" }, "identityIssuingCountry": { "type": "string" }, "identityType": { "type": "string" }, "identityNumber": { "type": "string" }, "identityExpiryDate": { "type": "string" }, "cellNumber": { "type": "string" }, "email": { "type": "string" }, "gender": { "type": "string" }, "purpose": { "type": "string" }, "employmentStatus": { "type": "string" }, "sourceOfFunds": { "type": "string" } }, "required": [ "id", "label" ] }, "ServerTime": { "type": "object", "properties": { "epochTime": { "type": "integer", "format": "int64" }, "time": { "type": "string" } }, "required": [ "epochTime", "time" ] }, "V1MarketSummaryRecordForApi": { "type": "object", "properties": { "currencyPair": { "type": "string" }, "askPrice": { "type": "string" }, "bidPrice": { "type": "string" }, "lastTradedPrice": { "type": "string" }, "previousClosePrice": { "type": "string" }, "baseVolume": { "type": "string" }, "quoteVolume": { "type": "string" }, "highPrice": { "type": "string" }, "lowPrice": { "type": "string" }, "created": { "type": "string" }, "changeFromPrevious": { "type": "string" }, "markPrice": { "type": "string" } }, "required": [ "currencyPair", "askPrice", "bidPrice", "lastTradedPrice", "previousClosePrice", "baseVolume", "quoteVolume", "highPrice", "lowPrice", "created", "changeFromPrevious" ] }, "V1CurrencyForApi": { "type": "object", "properties": { "symbol": { "type": "string" }, "isActive": { "type": "boolean" }, "shortName": { "type": "string" }, "longName": { "type": "string" }, "decimalPlaces": { "type": "string" }, "withdrawalDecimalPlaces": { "type": "string" }, "paymentReferenceFieldName": { "type": "string" }, "collateral": { "type": "boolean" }, "collateralWeight": { "type": "string" }, "defaultNetworkType": { "type": "string" }, "supportedNetworks": { "type": "array", "items": { "$ref": "#/components/schemas/V1SupportedNetworkForApi" } } }, "required": [ "symbol", "isActive", "shortName", "longName", "decimalPlaces", "withdrawalDecimalPlaces", "collateral", "collateralWeight" ] }, "V1SupportedNetworkForApi": { "type": "object", "properties": { "networkType": { "type": "string" }, "networkLongName": { "type": "string" }, "tokenContract": { "type": "string" }, "minimumWithdrawAmount": { "type": "string" }, "estimatedSendCost": { "type": "string" }, "deposit": { "type": "boolean" }, "withdraw": { "type": "boolean" }, "withdrawalDecimalPlaces": { "type": "string" } }, "required": [ "networkType", "deposit", "withdraw" ] }, "V1CurrencyPairForApi": { "type": "object", "properties": { "symbol": { "type": "string" }, "baseCurrency": { "type": "string" }, "quoteCurrency": { "type": "string" }, "shortName": { "type": "string" }, "active": { "type": "boolean" }, "minBaseAmount": { "type": "string" }, "maxBaseAmount": { "type": "string" }, "minQuoteAmount": { "type": "string" }, "maxQuoteAmount": { "type": "string" }, "tickSize": { "type": "string" }, "baseDecimalPlaces": { "type": "string" }, "marginTradingAllowed": { "type": "boolean" }, "currencyPairType": { "type": "string" }, "initialMarginFraction": { "type": "string" }, "maintenanceMarginFraction": { "type": "string" }, "autoCloseMarginFraction": { "type": "string" } }, "required": [ "symbol", "baseCurrency", "quoteCurrency", "shortName", "active", "minBaseAmount", "maxBaseAmount", "minQuoteAmount", "maxQuoteAmount", "tickSize", "baseDecimalPlaces", "marginTradingAllowed", "currencyPairType" ] }, "InternalCreateBulkWithdrawalBatchRequest": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "$ref": "#/components/schemas/BulkWithdrawalItemRequest" }, "description": "The payouts to make, one per recipient." }, "label": { "type": "string", "maxLength": 64, "nullable": true, "description": "Your label for the batch, up to 64 characters. Defaults to the creation time in South African time, e.g. `23-10-26-10:15`." } }, "required": [ "withdrawals" ] }, "BulkWithdrawalItemRequest": { "type": "object", "properties": { "bank": { "type": "string", "minLength": 1, "description": "Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive." }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 64, "pattern": "^[a-zA-Z0-9\\s.'_\\-(),&/]+$", "description": "Name on the recipient's bank account, 4 to 64 characters." }, "accountNumber": { "type": "string", "pattern": "^\\d{4,18}$", "description": "Recipient's account number, 4 to 18 digits." }, "branchCode": { "type": "string", "pattern": "^\\d{6}$", "description": "Recipient's branch code, 6 digits." }, "accountType": { "type": "string", "description": "Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive." }, "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Amount to pay in ZAR, greater than zero with at most two decimal places." }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9 /'-]{1,35}$", "nullable": true, "description": "Payment reference for this payout: up to 35 letters, digits, spaces, `/`, `'` or `-`." }, "email": { "type": "string", "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "nullable": true, "description": "Recipient's email address. Saved on their beneficiary, not sent with the payout." }, "type": { "type": "string", "nullable": true, "description": "`INDIVIDUAL` or `BUSINESS`. Saved on the recipient's beneficiary. Case-insensitive." }, "tradingName": { "type": "string", "pattern": "^[a-zA-Z0-9\\s.,'_\\-/&()]{1,64}$", "nullable": true, "description": "Recipient's trading name. Saved on their beneficiary, not sent with the payout." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "nullable": true, "description": "Recipient's country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`. Saved on their beneficiary." } }, "required": [ "bank" ] }, "UpdateBulkWithdrawalBatchLabelRequest": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 64, "minLength": 1, "description": "New label, up to 64 characters." } }, "required": [ "label" ] }, "CreateBeneficiaryRequest": { "type": "object", "properties": { "bank": { "type": "string", "minLength": 1, "description": "Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive." }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 64, "pattern": "^[a-zA-Z0-9\\s.'_\\-(),&/]+$" }, "accountNumber": { "type": "string", "pattern": "^\\d{4,18}$" }, "branchCode": { "type": "string", "pattern": "^\\d{6}$" }, "accountType": { "type": "string", "description": "Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive." }, "email": { "type": "string", "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "nullable": true }, "type": { "type": "string", "description": "`INDIVIDUAL` or `BUSINESS`. Case-insensitive." }, "tradingName": { "type": "string", "pattern": "^[a-zA-Z0-9\\s.,'_\\-/&()]{1,64}$", "nullable": true }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9 /'-]{1,35}$", "nullable": true, "description": "Default payment reference for this beneficiary. It isn't applied to payouts automatically: send it as the withdrawal's `reference`." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "nullable": true, "description": "Country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`." } }, "required": [ "bank" ] }, "UpdateBeneficiaryRequest": { "type": "object", "properties": { "bank": { "type": "string", "minLength": 1, "description": "Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive." }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 64, "pattern": "^[a-zA-Z0-9\\s.'_\\-(),&/]+$" }, "accountNumber": { "type": "string", "pattern": "^\\d{4,18}$" }, "branchCode": { "type": "string", "pattern": "^\\d{6}$" }, "accountType": { "type": "string", "description": "Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive." }, "type": { "type": "string", "description": "`INDIVIDUAL` or `BUSINESS`. Case-insensitive." }, "email": { "type": "string", "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "nullable": true }, "tradingName": { "type": "string", "pattern": "^[a-zA-Z0-9\\s.,'_\\-/&()]{1,64}$", "nullable": true }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9 /'-]{1,35}$", "nullable": true, "description": "Default payment reference for this beneficiary. It isn't applied to payouts automatically: send it as the withdrawal's `reference`." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "nullable": true, "description": "Country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`." } }, "required": [ "bank" ] }, "CreateBeneficiariesRequest": { "type": "object", "properties": { "beneficiaries": { "type": "array", "items": { "$ref": "#/components/schemas/CreateBeneficiaryRequest" }, "description": "The beneficiaries to save, each validated as for `POST /v2/payments/bulk-withdrawals/beneficiaries`." } }, "required": [ "beneficiaries" ] }, "FeeQuoteRequest": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "$ref": "#/components/schemas/FeeQuoteItemRequest" } } }, "required": [ "withdrawals" ] }, "FeeQuoteItemRequest": { "type": "object", "properties": { "bank": { "type": "string", "minLength": 1, "description": "Bank code, e.g. `FNB`. Decides whether the withdrawal is quoted as fast or regular." }, "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Amount in ZAR, greater than zero with at most two decimal places." } }, "required": [ "bank" ] }, "BulkWithdrawalBatchForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "currency": { "type": "string" }, "totalAmount": { "type": "string", "description": "Sum of the withdrawal amounts, as a decimal string." }, "withdrawalCount": { "type": "integer", "format": "int32" }, "status": { "type": "string", "description": "Batch status: `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED` or `CANCELLED`." }, "uploadedBy": { "type": "string", "description": "ID of the user or API key that created the batch." }, "uploadedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true }, "approvedBy": { "type": "string", "nullable": true, "description": "ID of the user or API key that approved the batch (for a batch created with an API key, that key); `null` until approved." }, "approvedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true }, "approvedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "feeQuote": { "allOf": [ { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" } ], "nullable": true, "description": "Fee for the batch's pending withdrawals, or the fee charged once none are pending. Only returned by `GET /v2/payments/bulk-withdrawals/batches/{id}`; `null` elsewhere, and when the fee can't be quoted." } }, "required": [ "id", "label", "currency", "totalAmount", "withdrawalCount", "status", "uploadedBy", "uploadedByName", "approvedBy", "approvedByName", "approvedAt", "createdAt", "updatedAt", "completedAt", "feeQuote" ] }, "ResolvedUserName": { "type": "object", "properties": { "name": { "type": "string" }, "surname": { "type": "string" } }, "required": [ "name", "surname" ] }, "DisbursementFeeQuoteForDisplay": { "type": "object", "properties": { "fee": { "type": "string", "nullable": true, "description": "Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee." }, "currency": { "type": "string" }, "withdrawalCount": { "type": "integer", "format": "int32", "description": "Number of withdrawals the fee covers." }, "grossTotal": { "type": "string", "description": "Sum of those withdrawals' amounts." }, "requiredTotal": { "type": "string", "description": "Gross total plus fee: the available balance your payout account needs." }, "feeGroups": { "type": "array", "items": { "$ref": "#/components/schemas/DisbursementFeeGroupForDisplay" }, "nullable": true, "description": "Breakdown by fee type; `null` when the quote is the fee already charged." } }, "required": [ "fee", "currency", "withdrawalCount", "grossTotal", "requiredTotal", "feeGroups" ] }, "DisbursementFeeGroupForDisplay": { "type": "object", "properties": { "actionType": { "type": "string", "description": "`FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`." }, "withdrawalCount": { "type": "integer", "format": "int32" }, "grossTotal": { "type": "string" } }, "required": [ "actionType", "withdrawalCount", "grossTotal" ] }, "AccountBalanceResponse": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/CurrencyDto" }, "available": { "type": "string", "description": "Balance available to use, as a decimal string." }, "reserved": { "type": "string", "description": "Balance that is reserved and not available, as a decimal string." }, "total": { "type": "string", "description": "Available plus reserved, as a decimal string." } }, "required": [ "currency", "available", "reserved", "total" ] }, "CurrencyDto": { "type": "object", "properties": { "shortName": { "type": "string" }, "symbol": { "type": "string", "nullable": true }, "longName": { "type": "string", "nullable": true } }, "required": [ "shortName", "symbol", "longName" ] }, "BankDefinition": { "type": "object", "properties": { "code": { "type": "string", "description": "Bank code to send as `bank`." }, "displayName": { "type": "string" }, "defaultBranchCode": { "type": "string", "description": "The bank's universal branch code; empty if it has none." }, "rtcParticipant": { "type": "boolean", "description": "Whether the bank takes real-time payments. Payouts to these banks are sent, and charged, as fast withdrawals." } }, "required": [ "code", "displayName", "defaultBranchCode", "rtcParticipant" ] }, "PaginatedBulkWithdrawalBatchForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "nullable": true } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "InternalCreateBulkWithdrawalBatchResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Batch ID." } }, "required": [ "id" ] }, "PaginatedBulkWithdrawalForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BulkWithdrawalForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "nullable": true } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "BulkWithdrawalForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "uploadedBy": { "type": "string" }, "uploadedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true }, "approvedBy": { "type": "string", "nullable": true }, "approvedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true }, "amount": { "type": "string" }, "bank": { "type": "string" }, "bankDisplayName": { "type": "string" }, "accountType": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "linkedBankAccountId": { "type": "string", "format": "uuid", "nullable": true }, "withdrawalId": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "Withdrawal status: `PENDING`, `APPROVED`, `EXECUTING`, `SUBMITTED`, `PROCESSING`, `PAID`, `FAILED` or `SKIPPED`." }, "failureReason": { "type": "string", "nullable": true, "description": "Why the withdrawal failed; `null` unless it failed." }, "failureReasonCode": { "type": "string", "nullable": true, "description": "Failure category, e.g. `INSUFFICIENT_FUNDS` or `REVERSED`; `null` unless it failed." }, "reversed": { "type": "boolean" }, "feeReversed": { "type": "boolean", "description": "Whether the withdrawal's fee has been refunded." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastChangedAt": { "type": "string", "format": "date-time", "description": "When the status last changed or the fee was refunded; this is what `updatedSince` filters on." } }, "required": [ "id", "batchId", "uploadedBy", "uploadedByName", "approvedBy", "approvedByName", "amount", "bank", "bankDisplayName", "accountType", "accountHolder", "accountNumberMasked", "accountNumber", "branchCode", "reference", "linkedBankAccountId", "withdrawalId", "status", "failureReason", "failureReasonCode", "reversed", "feeReversed", "createdAt", "updatedAt", "lastChangedAt" ] }, "PaginatedBeneficiaryForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "nullable": true } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "BeneficiaryForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bank": { "type": "string" }, "bankDisplayName": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string", "description": "Account number with all but the last four digits masked." }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "description": "`INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch." }, "tradingName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true, "description": "Default payment reference for this beneficiary. It isn't applied to payouts automatically." }, "country": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastPaidAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When a payout to this beneficiary was last attempted; `null` if never." }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the beneficiary was archived; `null` if it's active." }, "deletedBy": { "type": "string", "nullable": true, "description": "ID of the user or API key that archived the beneficiary." } }, "required": [ "id", "bank", "bankDisplayName", "accountHolder", "accountNumberMasked", "accountNumber", "branchCode", "accountType", "email", "type", "tradingName", "reference", "country", "createdAt", "updatedAt", "lastPaidAt", "deletedAt", "deletedBy" ] }, "PaginatedWithdrawalWithBatchForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalWithBatchForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "nullable": true } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "WithdrawalWithBatchForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "string" }, "bank": { "type": "string" }, "bankDisplayName": { "type": "string" }, "accountType": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "linkedBankAccountId": { "type": "string", "format": "uuid", "nullable": true }, "withdrawalId": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "Withdrawal status: `PENDING`, `APPROVED`, `EXECUTING`, `SUBMITTED`, `PROCESSING`, `PAID`, `FAILED` or `SKIPPED`." }, "failureReason": { "type": "string", "nullable": true, "description": "Why the withdrawal failed; `null` unless it failed." }, "failureReasonCode": { "type": "string", "nullable": true, "description": "Failure category, e.g. `INSUFFICIENT_FUNDS` or `REVERSED`; `null` unless it failed." }, "reversed": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "batch": { "$ref": "#/components/schemas/MinimalBatchForDisplay", "description": "The batch the withdrawal belongs to." } }, "required": [ "id", "amount", "bank", "bankDisplayName", "accountType", "accountHolder", "accountNumberMasked", "accountNumber", "branchCode", "reference", "linkedBankAccountId", "withdrawalId", "status", "failureReason", "failureReasonCode", "reversed", "createdAt", "updatedAt", "batch" ] }, "MinimalBatchForDisplay": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "uploadedBy": { "type": "string" }, "uploadedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true }, "approvedBy": { "type": "string", "nullable": true }, "approvedByName": { "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ], "nullable": true } }, "required": [ "id", "label", "status", "uploadedBy", "uploadedByName", "approvedBy", "approvedByName" ] }, "PaginatedPayoutTransactionForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutTransactionForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "nullable": true } }, "required": [ "items", "total", "limit", "offset", "truncated" ] }, "PayoutTransactionForDisplay": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "description": "`DEBIT` (money out) or `CREDIT` (money in)." }, "kind": { "type": "string", "description": "`WITHDRAWAL` (a payout), `FUNDING` (an automated funding transfer), `FUNDING_MANUAL` (any other top-up) or `REVERSAL` (a reversed payout returned to the account)." }, "status": { "type": "string", "description": "`COMPLETE`, `PROCESSING`, `REVERSED` or `FAILED`." }, "amount": { "type": "string", "description": "Amount including any fee, as an unsigned decimal string; `direction` gives the sign." }, "currency": { "type": "string" }, "date": { "type": "integer", "format": "int64", "description": "When the transaction happened, in Unix milliseconds." }, "counterparty": { "type": "string", "nullable": true, "description": "The recipient's name for a debit; `Payout account` or `Reversal` for a credit." }, "reference": { "type": "string", "nullable": true, "description": "Payment reference, or `Funding` for a credit without one." }, "batchId": { "type": "string", "nullable": true }, "batchLabel": { "type": "string", "nullable": true }, "paymentId": { "type": "string", "nullable": true, "description": "For a funding credit, the ID of the payment that funded it; use it with `GET /v2/payments/{id}`." } }, "required": [ "id", "direction", "kind", "status", "amount", "currency", "date", "counterparty", "reference", "batchId", "batchLabel", "paymentId" ] }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "batchId": { "type": "string" } }, "required": [ "code", "message" ] }, "PagePaymentForUser": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentForUser" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "PaymentForUser": { "type": "object", "properties": { "id": { "type": "string", "description": "Payment ID." }, "depositId": { "type": "string", "nullable": true, "description": "ID of the deposit that created the payment." }, "status": { "type": "string", "description": "Overall status: `RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`." }, "mode": { "type": "string", "nullable": true, "description": "How the payment is paid out: `INSTANT` or `SCHEDULED`. Null until a payout is set up." }, "type": { "type": "string", "description": "`COLLECTION` for a payment from a payer, `DISBURSEMENT` for a deposit that funds disbursements." }, "inflowCurrency": { "type": "string" }, "inflowAmount": { "type": "string", "description": "Amount deposited." }, "convertedCurrency": { "type": "string", "nullable": true }, "convertedAmount": { "type": "string", "nullable": true, "description": "Amount after conversion; null if the deposit hasn't been converted." }, "outflowCurrency": { "type": "string", "nullable": true }, "outflowAmount": { "type": "string", "nullable": true, "description": "Amount paid out; null until a payout is set up." }, "receivedAt": { "type": "integer", "format": "int64", "description": "When the deposit was received, in Unix milliseconds." }, "settlementAt": { "type": "integer", "format": "int64", "nullable": true, "description": "Expected settlement time while a scheduled payout is pending, then the time the payment settled, in Unix milliseconds." }, "settlementStatus": { "type": "string", "nullable": true, "description": "`PENDING`, `SETTLED` or `FAILED`." }, "settlementRef": { "type": "string", "nullable": true, "description": "Payout reference, such as the blockchain transaction hash of a crypto payout." }, "settlementId": { "type": "string", "nullable": true, "description": "The settlement that paid this payment out; null until a payout has been requested." }, "linked": { "type": "boolean", "description": "Whether the deposit carries a payer reference." }, "payerName": { "type": "string", "nullable": true, "description": "Payer's name." }, "reference": { "type": "string", "nullable": true, "description": "Payer reference quoted with the deposit." }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStepForDisplay" }, "nullable": true, "description": "Steps the payment has been through. Only returned when you get a single payment." }, "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentPayoutForUser" }, "nullable": true, "description": "Settled payouts that carried this payment; more than one if it was split. Only returned when you get a single payment." } }, "required": [ "id", "depositId", "status", "mode", "type", "inflowCurrency", "inflowAmount", "convertedCurrency", "convertedAmount", "outflowCurrency", "outflowAmount", "receivedAt", "settlementAt", "settlementStatus", "settlementRef", "settlementId", "linked", "payerName", "reference", "timeline", "payouts" ] }, "FlowStepForDisplay": { "type": "object", "properties": { "type": { "type": "string", "description": "`FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`." }, "label": { "type": "string" }, "status": { "type": "string", "description": "`PENDING`, `COMPLETE` or `FAILED`." }, "data": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Amounts and currencies for the step." }, "traceId": { "type": "string", "nullable": true, "description": "Reference you can quote to support, such as a conversion ID or blockchain transaction hash." }, "at": { "type": "integer", "format": "int64", "description": "When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time." } }, "required": [ "type", "label", "status", "data", "traceId", "at" ] }, "PaymentPayoutForUser": { "type": "object", "properties": { "settlementId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string", "description": "Payout status. Only settled payouts are listed, so this is `SETTLED`." }, "settledAt": { "type": "integer", "format": "int64", "nullable": true, "description": "When the payout settled, in Unix milliseconds." } }, "required": [ "settlementId", "amount", "currency", "status", "settledAt" ] }, "PageScheduledWithdrawalEventForUser": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledWithdrawalEventForUser" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "ScheduledWithdrawalEventForUser": { "type": "object", "properties": { "id": { "type": "string" }, "withdrawalCurrency": { "type": "string" }, "withdrawalAmount": { "type": "string", "description": "Amount the payment adds to the payout." }, "receivedAt": { "type": "integer", "format": "int64", "description": "When the payment joined the schedule, in Unix milliseconds." }, "status": { "type": "string", "description": "`QUEUED`, `SCHEDULED`, `PROCESSING`, `COMPLETED`, `FAILED` or `REVERSED`." }, "depositCurrency": { "type": "string", "nullable": true }, "depositAmount": { "type": "string", "nullable": true, "description": "Amount of the deposit the payment came from." }, "payerName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStepForDisplay" }, "nullable": true, "description": "Steps the payment has been through. Only returned when you get a single scheduled payment." } }, "required": [ "id", "withdrawalCurrency", "withdrawalAmount", "receivedAt", "status", "depositCurrency", "depositAmount", "payerName", "reference", "timeline" ] }, "WithdrawalRunForDisplay": { "type": "object", "properties": { "id": { "type": "string" }, "scheduledFor": { "type": "integer", "format": "int64", "description": "When the run pays out, in Unix milliseconds." }, "cutoffAt": { "type": "integer", "format": "int64", "description": "Payments received after this time wait for the next run, in Unix milliseconds." }, "status": { "type": "string", "description": "`PENDING`, `PROCESSING`, `DONE`, `FAILED`, `CANCELLED` or `REVERSED`." }, "totalAmount": { "type": "string", "description": "Total the run pays out; `0` until the run starts." }, "currency": { "type": "string" }, "createdAt": { "type": "integer", "format": "int64" } }, "required": [ "id", "scheduledFor", "cutoffAt", "status", "totalAmount", "currency", "createdAt" ] }, "PageWithdrawalRunForDisplay": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalRunForDisplay" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "WithdrawalScheduleForDisplay": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "kind": { "type": "string", "description": "`FIAT` to pay out to a bank account, `CRYPTO` to pay out to a wallet." }, "intervalType": { "type": "string", "description": "`DAILY` or `WEEKLY`." }, "timeOfDay": { "type": "string", "description": "Local time the run pays out, as `HH:mm` in `zoneId`." }, "zoneId": { "type": "string", "description": "IANA time zone of `timeOfDay`." }, "dayOfWeek": { "type": "integer", "format": "int32", "nullable": true, "description": "Day of a `WEEKLY` run, from 1 (Monday) to 7 (Sunday); null for `DAILY`." }, "cutoffMinutes": { "type": "integer", "format": "int32", "description": "Payments received less than this many minutes before a run wait for the next one." }, "paymentInstrumentId": { "type": "string", "description": "The bank account or wallet the schedule pays out to." }, "isActive": { "type": "boolean", "description": "Whether the schedule is running." }, "createdAt": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "integer", "format": "int64" } }, "required": [ "id", "currency", "kind", "intervalType", "timeOfDay", "zoneId", "dayOfWeek", "cutoffMinutes", "paymentInstrumentId", "isActive", "createdAt", "updatedAt" ] }, "PageSettlementForUser": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementForUser" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "SettlementForUser": { "type": "object", "properties": { "id": { "type": "string", "description": "Settlement ID: the payout run ID for a scheduled payout, or the payout ID for an instant payout." }, "currency": { "type": "string", "nullable": true, "description": "Payout currency." }, "totalAmount": { "type": "string", "description": "Total the settlement pays out." }, "settledAmount": { "type": "string", "description": "Amount paid out so far; equals `totalAmount` once fully settled." }, "paymentCount": { "type": "integer", "format": "int32" }, "status": { "type": "string", "description": "`PENDING`, `SETTLED`, `FAILED` or `PARTIALLY_SETTLED`." }, "settledAt": { "type": "integer", "format": "int64", "nullable": true, "description": "Latest time a payment in the settlement settled, in Unix milliseconds; null if none has." }, "receivedAt": { "type": "integer", "format": "int64", "description": "When the most recent payment in the settlement was received, in Unix milliseconds." } }, "required": [ "id", "currency", "totalAmount", "settledAmount", "paymentCount", "status", "settledAt", "receivedAt" ] }, "SettlementWalletForUser": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID." }, "name": { "type": "string", "nullable": true, "description": "Label you gave the wallet." }, "address": { "type": "string" }, "network": { "type": "string", "nullable": true, "description": "Blockchain network of the wallet." }, "currency": { "type": "string" }, "beneficiaryName": { "type": "string", "nullable": true, "description": "Name of the wallet's owner." }, "serviceProviderName": { "type": "string", "nullable": true, "description": "Provider that hosts the wallet, if recorded." } }, "required": [ "id", "name", "address", "network", "currency", "beneficiaryName", "serviceProviderName" ] }, "UpcomingWithdrawalForUser": { "type": "object", "properties": { "scheduleId": { "type": "string" }, "currency": { "type": "string" }, "nextRunAt": { "type": "integer", "format": "int64", "nullable": true, "description": "When the next run pays out, in Unix milliseconds; null if nothing is queued." }, "cutoffAt": { "type": "integer", "format": "int64", "nullable": true, "description": "Cut-off for the next run, in Unix milliseconds; null if nothing is queued." }, "totalAmount": { "type": "string", "description": "Total queued for the next run." }, "eventCount": { "type": "integer", "format": "int32", "description": "Number of payments queued for the next run." } }, "required": [ "scheduleId", "currency", "nextRunAt", "cutoffAt", "totalAmount", "eventCount" ] }, "PageCollectionActivityForUser": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionActivityForUser" } }, "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" } }, "required": [ "items", "total", "limit", "offset" ] }, "CollectionActivityForUser": { "type": "object", "properties": { "kind": { "type": "string", "description": "`PAYMENT` for a payment received from a payer, `SETTLEMENT` for collected funds paid out." }, "id": { "type": "string" }, "date": { "type": "integer", "format": "int64", "description": "When the payment was received or the settlement paid out, in Unix milliseconds." }, "status": { "type": "string", "description": "For `PAYMENT` entries, the payment status (`RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`). `SETTLEMENT` entries are always `SETTLED`." }, "amount": { "type": "string" }, "currency": { "type": "string", "nullable": true }, "convertedAmount": { "type": "string", "nullable": true }, "convertedCurrency": { "type": "string", "nullable": true }, "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "paymentId": { "type": "string", "nullable": true, "description": "Payment ID for `PAYMENT` entries; use it with Get a payment." }, "settlementId": { "type": "string", "nullable": true, "description": "The settlement this entry belongs to; use it with Get a settlement." } }, "required": [ "kind", "id", "date", "status", "amount", "currency", "convertedAmount", "convertedCurrency", "from", "to", "reference", "paymentId", "settlementId" ] } } }, "tags": [ { "name": "Balances", "description": "Account balances." }, { "name": "Sub-accounts", "description": "Your business's primary account and its sub-accounts: list, create, rename and delete sub-accounts, and move funds between your accounts. Your primary account's ID is `0`. To call another endpoint on a sub-account, send the sub-account's `id` in the `X-VALR-SUB-ACCOUNT-ID` header; without it, requests act on your primary account. A key limited to some sub-accounts can only act on those, so it must always send the header." }, { "name": "Transaction history", "description": "Transactions and trades on your accounts, newest first. Unless an endpoint says otherwise, it reads the account you call it on: your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`. An account's history doesn't include its sub-accounts' transactions." }, { "name": "Crypto deposits", "description": "Deposit addresses for receiving crypto, and the history of crypto deposits to your accounts." }, { "name": "Crypto withdrawals", "description": "Send crypto to an address or a saved address-book entry, check a currency's withdrawal settings and your limits, and follow each withdrawal's progress. Withdrawals to an address hosted by another provider need the recipient's details." }, { "name": "Address book", "description": "Saved withdrawal addresses, with the recipient's details where they've been added. Your business can require crypto withdrawals to go only to these addresses." }, { "name": "Bank accounts", "description": "Bank accounts you withdraw fiat to, and the banks you can link. Each bank account belongs to one account, the primary or a sub-account, and only that account can withdraw to it." }, { "name": "Fiat deposits", "description": "References to quote when you deposit fiat by bank transfer, including auto-buy references that use the deposit to buy another currency." }, { "name": "Fiat withdrawals", "description": "Withdraw fiat to a linked bank account or pay a bank beneficiary in one call, estimate fees, and track withdrawals." }, { "name": "Deposit references", "description": "Unique references your payers quote when they deposit, so each deposit can be matched to a payer." }, { "name": "Getting paid", "description": "Deposits your business receives, from payers or to fund disbursements, and how each one is converted and paid out." }, { "name": "Collection schedules", "description": "Schedules that pay collected funds out at set times, the payments queued for each run, and the runs themselves." }, { "name": "Settlements", "description": "Payouts of collected funds, made instantly or by a scheduled run, and the payments each one paid out." }, { "name": "Disbursements", "description": "Batches of payouts to beneficiaries." }, { "name": "Beneficiaries", "description": "Recipients you pay out to. Recipients in each disbursement batch are also saved as beneficiaries automatically." }, { "name": "Payments balances", "description": "Balances of your business's payments accounts: payouts, collections, funding and amounts on hold." }, { "name": "Webhooks", "description": "Get HTTPS notifications when events happen on your business's accounts, such as deposits being credited or withdrawals changing status. A webhook receives events for your primary account and all its sub-accounts. Each delivery is a `POST` with a JSON body and the headers `Valr-Webhook-Event-Id`, `Valr-Webhook-Event-Type`, `Valr-Webhook-Timestamp` (Unix milliseconds), `Valr-Webhook-Delivery-Attempt` and `Valr-Webhook-Signature`. To verify a delivery, compute the HMAC-SHA256 of `{Valr-Webhook-Timestamp}.{raw body}`, keyed with the signing secret exactly as it was returned (don't base64-decode it), and compare its lowercase hex with the value after `v1=` in `Valr-Webhook-Signature`; ignore any other versions you don't recognise. Respond with a 2xx status within a few seconds. Deliveries that can't connect, time out or get a 408, 429 or 5xx response are retried with increasing delays for up to about two days; other responses, including redirects, aren't retried. The same event can arrive more than once, so use `Valr-Webhook-Event-Id` to discard duplicates. API keys restricted to sub-accounts can't use the webhook endpoints, apart from listing event types." }, { "name": "Status and time", "description": "Whether VALR is accepting all requests, and the server's clock for checking your request timestamps. These endpoints are public, so no API key is needed." }, { "name": "Currencies and pairs", "description": "The currencies and currency pairs VALR lists, with each pair's trading limits, the order types it accepts and its slippage limits. These endpoints are public, so no API key is needed." }, { "name": "Market prices", "description": "Market summaries and price buckets for every currency pair, with no API key needed. Responses can be up to 5 seconds old." } ], "x-tagGroups": [ { "name": "Account", "tags": [ "Balances", "Sub-accounts", "Transaction history" ] }, { "name": "Wallets", "tags": [ "Crypto deposits", "Crypto withdrawals", "Address book", "Bank accounts", "Fiat deposits", "Fiat withdrawals" ] }, { "name": "Collections", "tags": [ "Getting paid", "Deposit references", "Collection schedules", "Settlements" ] }, { "name": "Payouts", "tags": [ "Disbursements", "Beneficiaries", "Payments balances" ] }, { "name": "Webhooks", "tags": [ "Webhooks" ] }, { "name": "Public data", "tags": [ "Status and time", "Currencies and pairs", "Market prices" ] } ], "x-valr-error-reference": { "common": [ { "title": "Authentication and authorisation", "errors": [ { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "reason": "The `X-VALR-API-KEY` header is missing." }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "reason": "The `X-VALR-SIGNATURE` header is missing." }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "reason": "The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds." }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "reason": "The API key doesn't exist or has been revoked." }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "reason": "The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID." }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the past. Sign each request just before sending it." }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "reason": "The timestamp is too far in the future. Check your clock." }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "reason": "This exact signed request has already been used. Each signature is accepted once." }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "reason": "The request came from an IP address outside the key's allowed list." }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "reason": "The key's allowed-endpoints list doesn't include this endpoint." }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "reason": "The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable." } ] } ], "endpoints": [ { "operationId": "getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "method": "GET", "path": "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}", "summary": "Get a deposit reference", "errors": [ { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ] }, { "operationId": "deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "method": "DELETE", "path": "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}", "summary": "Delete a deposit reference", "errors": [ { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ] }, { "operationId": "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "method": "PUT", "path": "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}", "summary": "Update a deposit reference", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ] }, { "operationId": "postV2WalletFiatByCurrencyPaymentReferences", "method": "POST", "path": "/v2/wallet/fiat/{currency}/payment/references", "summary": "Create a deposit reference", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "code": -15116, "name": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Daily deposit reference generation limit exceeded", "reason": "You've reached the daily limit for creating references." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "code": -15119, "name": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Total deposit reference limit reached", "reason": "You've reached the maximum number of references." } ] }, { "operationId": "getV2WalletFiatByCurrencyPaymentReferences", "method": "GET", "path": "/v2/wallet/fiat/{currency}/payment/references", "summary": "List deposit references", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`matched` isn't `true` or `false`, `skip` or `limit` isn't a whole number, `query`, `name` or `email` is empty or too long, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." } ] }, { "operationId": "getV1AccountBalances", "method": "GET", "path": "/v1/account/balances", "summary": "Get balances", "errors": [] }, { "operationId": "getV2PaymentsBulkWithdrawalsBatchesById", "method": "GET", "path": "/v2/payments/bulk-withdrawals/batches/{id}", "summary": "Get a disbursement batch", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ] }, { "operationId": "getV1Webhooks", "method": "GET", "path": "/v1/webhooks", "summary": "List webhooks", "errors": [] }, { "operationId": "postV1Webhooks", "method": "POST", "path": "/v1/webhooks", "summary": "Create a webhook", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "code": -18122, "name": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "httpStatus": 400, "message": "Webhook subscription limit reached:", "reason": "Your business already has the maximum number of webhooks. Delete one you no longer need, then try again." } ] }, { "operationId": "deleteV1WebhooksById", "method": "DELETE", "path": "/v1/webhooks/{id}", "summary": "Delete a webhook", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID, or the `Content-Type: application/json` header is missing." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ] }, { "operationId": "getV1WebhooksById", "method": "GET", "path": "/v1/webhooks/{id}", "summary": "Get a webhook", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ] }, { "operationId": "putV1WebhooksById", "method": "PUT", "path": "/v1/webhooks/{id}", "summary": "Update a webhook", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ] }, { "operationId": "getV1WebhooksByIdDeliveries", "method": "GET", "path": "/v1/webhooks/{id}/deliveries", "summary": "List webhook delivery attempts", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID isn't a valid UUID, `skip` or `limit` isn't an integer, or `limit` is more than 100." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." } ] }, { "operationId": "getV1WebhooksByIdEventsByEventId", "method": "GET", "path": "/v1/webhooks/{id}/events/{eventId}", "summary": "Get a webhook event", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The webhook ID or event ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "reason": "No webhook with this ID exists for your business." }, { "ref": "ApplicationErrorCodes.WEBHOOK_EVENT_NOT_FOUND", "code": -18123, "name": "WEBHOOK_EVENT_NOT_FOUND", "httpStatus": 404, "message": "Webhook event not found", "reason": "This webhook hasn't sent an event with this ID." } ] }, { "operationId": "getV1WebhooksEventTypes", "method": "GET", "path": "/v1/webhooks/event-types", "summary": "List webhook event types", "errors": [] }, { "operationId": "postV2WalletFiatByCurrencyPaymentBulkReferences", "method": "POST", "path": "/v2/wallet/fiat/{currency}/payment/bulk-references", "summary": "Create deposit references in bulk", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "code": -15121, "name": "BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "httpStatus": 400, "message": "Batch size exceeds maximum allowed", "reason": "`senders` has more payers than a single batch allows. Split them into smaller batches." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "code": -15124, "name": "BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "httpStatus": 409, "message": "A bulk deposit job is already being processed", "reason": "An earlier bulk job is still processing. Wait for it to finish, then try again." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "code": -15123, "name": "BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "httpStatus": 400, "message": "Invalid sender information", "reason": "An entry in `senders` is `null`, a payer's name or email is missing or invalid, or their expected amount isn't a number greater than zero; the message identifies up to three such payers by their position in `senders`, and no job is created." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "code": -15119, "name": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Total deposit reference limit reached", "reason": "The batch would take you past the maximum number of references. Delete references you no longer need or submit fewer payers." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "code": -15116, "name": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Daily deposit reference generation limit exceeded", "reason": "The batch would take you past the daily limit for creating references. Submit fewer payers or try again tomorrow." } ] }, { "operationId": "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "method": "GET", "path": "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}", "summary": "Get a bulk reference job", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The job ID isn't a whole number, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "code": -15122, "name": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "httpStatus": 404, "message": "Bulk deposit job not found", "reason": "No bulk job with this ID exists on your account for this currency." } ] }, { "operationId": "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems", "method": "GET", "path": "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items", "summary": "List bulk reference job items", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The job ID, `skip` or `limit` isn't a whole number, `status` isn't `PENDING`, `SUCCESS` or `FAILED`, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "reason": "Bulk deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "code": -15122, "name": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "httpStatus": 404, "message": "Bulk deposit job not found", "reason": "No bulk job with this ID exists on your account for this currency." } ] }, { "operationId": "getV2WalletFiatByCurrencyPaymentDeposits", "method": "GET", "path": "/v2/wallet/fiat/{currency}/payment/deposits", "summary": "List credited deposits", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, or the currency isn't recognised." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "reason": "Deposit references are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your collections account doesn't support this currency." } ] }, { "operationId": "deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "method": "DELETE", "path": "/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference", "summary": "Unlink a deposit from its reference", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The deposit ID isn't a valid UUID." }, { "ref": "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND", "code": -15118, "name": "FIAT_DEPOSIT_NOT_FOUND", "httpStatus": 404, "message": "Deposit not found", "reason": "No deposit with this ID exists on your collections account." } ] }, { "operationId": "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "method": "PUT", "path": "/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference", "summary": "Link a deposit to a reference", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND", "code": -15118, "name": "FIAT_DEPOSIT_NOT_FOUND", "httpStatus": 404, "message": "Deposit not found", "reason": "No deposit with this ID exists on your collections account." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "code": -15115, "name": "UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "httpStatus": 400, "message": "Deposit override is invalid", "reason": "The deposit hasn't been fully credited yet." }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "reason": "No reference with this code exists on your account." } ] }, { "operationId": "getV2Payments", "method": "GET", "path": "/v2/payments", "summary": "List payments", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsById", "method": "GET", "path": "/v2/payments/{id}", "summary": "Get a payment", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The payment ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payment with this ID exists in your business." } ] }, { "operationId": "getV2PaymentsCollectEvents", "method": "GET", "path": "/v2/payments/collect/events", "summary": "List queued scheduled payments", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectEventsById", "method": "GET", "path": "/v2/payments/collect/events/{id}", "summary": "Get a scheduled payment", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The scheduled payment ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No scheduled payment with this ID exists on your business's payout schedules." } ] }, { "operationId": "getV2PaymentsCollectHistory", "method": "GET", "path": "/v2/payments/collect/history", "summary": "List processed scheduled payments", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectRunsById", "method": "GET", "path": "/v2/payments/collect/runs/{id}", "summary": "Get a payout run", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The run ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payout run with this ID exists on your business's payout schedules." } ] }, { "operationId": "getV2PaymentsCollectRunsByIdPayments", "method": "GET", "path": "/v2/payments/collect/runs/{id}/payments", "summary": "List a payout run's payments", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The run ID isn't a valid UUID." } ] }, { "operationId": "getV2PaymentsCollectRunsHistory", "method": "GET", "path": "/v2/payments/collect/runs/history", "summary": "List payout runs", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectSchedules", "method": "GET", "path": "/v2/payments/collect/schedules", "summary": "List payout schedules", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectSettlements", "method": "GET", "path": "/v2/payments/collect/settlements", "summary": "List settlements", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectSettlementsById", "method": "GET", "path": "/v2/payments/collect/settlements/{id}", "summary": "Get a settlement", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement with this ID exists in your business." } ] }, { "operationId": "getV2PaymentsCollectSettlementsByIdPayments", "method": "GET", "path": "/v2/payments/collect/settlements/{id}/payments", "summary": "List a settlement's payments", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement with this ID exists in your business." } ] }, { "operationId": "getV2PaymentsCollectSettlementsWallet", "method": "GET", "path": "/v2/payments/collect/settlements/wallet", "summary": "Get the settlement wallet", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No settlement wallet is set up for your business." } ] }, { "operationId": "getV2PaymentsCollectUpcoming", "method": "GET", "path": "/v2/payments/collect/upcoming", "summary": "Get upcoming scheduled payouts", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsCollectionsHistory", "method": "GET", "path": "/v2/payments/collections/history", "summary": "List collection activity", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsAccountBalancesByType", "method": "GET", "path": "/v2/payments/account/balances/{type}", "summary": "Get payments account balances", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`type` isn't one of `PAYOUT`, `COLLECTIONS`, `FUNDING` or `HOLD`." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "Your business has no account of this type set up for `currency`." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBanks", "method": "GET", "path": "/v2/payments/bulk-withdrawals/banks", "summary": "List supported banks", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBatches", "method": "GET", "path": "/v2/payments/bulk-withdrawals/batches", "summary": "List disbursement batches", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "postV2PaymentsBulkWithdrawalsBatches", "method": "POST", "path": "/v2/payments/bulk-withdrawals/batches", "summary": "Create a disbursement batch", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or has no `withdrawals` array, or `X-VALR-Idempotency-Key` isn't valid, in which case `validationErrors` names the header." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "The idempotency key belongs to a batch that was cancelled, so retry with a new key, or to one that failed after its fee was charged, so contact support instead of retrying." } ] }, { "operationId": "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "method": "POST", "path": "/v2/payments/bulk-withdrawals/batches/{id}/cancel", "summary": "Cancel a disbursement batch", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "method": "GET", "path": "/v2/payments/bulk-withdrawals/batches/{id}/fee-quote", "summary": "Get a batch's fee quote", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ] }, { "operationId": "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "method": "PUT", "path": "/v2/payments/bulk-withdrawals/batches/{id}/label", "summary": "Rename a disbursement batch", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "method": "GET", "path": "/v2/payments/bulk-withdrawals/batches/{id}/withdrawals", "summary": "List a batch's withdrawals", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The batch ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No batch with this ID exists on your account." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBeneficiaries", "method": "GET", "path": "/v2/payments/bulk-withdrawals/beneficiaries", "summary": "List beneficiaries", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "postV2PaymentsBulkWithdrawalsBeneficiaries", "method": "POST", "path": "/v2/payments/bulk-withdrawals/beneficiaries", "summary": "Create a beneficiary", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "An active beneficiary with this bank and account number already exists; update it instead." } ] }, { "operationId": "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "method": "DELETE", "path": "/v2/payments/bulk-withdrawals/beneficiaries/{id}", "summary": "Archive a beneficiary", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The beneficiary ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No active beneficiary with this ID exists on your account; it may already be archived." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsBeneficiariesById", "method": "GET", "path": "/v2/payments/bulk-withdrawals/beneficiaries/{id}", "summary": "Get a beneficiary", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The beneficiary ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No beneficiary with this ID exists on your account." } ] }, { "operationId": "putV2PaymentsBulkWithdrawalsBeneficiariesById", "method": "PUT", "path": "/v2/payments/bulk-withdrawals/beneficiaries/{id}", "summary": "Update a beneficiary", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No active beneficiary with this ID exists on your account; archived beneficiaries can't be updated." }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "reason": "Another beneficiary, active or archived, already has this bank and account number." } ] }, { "operationId": "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "method": "POST", "path": "/v2/payments/bulk-withdrawals/beneficiaries/bulk", "summary": "Create beneficiaries in bulk", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "postV2PaymentsBulkWithdrawalsFeeQuote", "method": "POST", "path": "/v2/payments/bulk-withdrawals/fee-quote", "summary": "Quote fees for withdrawals", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsBulkWithdrawalsWithdrawals", "method": "GET", "path": "/v2/payments/bulk-withdrawals/withdrawals", "summary": "List withdrawals", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsPayoutHistory", "method": "GET", "path": "/v2/payments/payout/history", "summary": "List payout account transactions", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." } ] }, { "operationId": "getV2PaymentsPayoutHistoryById", "method": "GET", "path": "/v2/payments/payout/history/{id}", "summary": "Get a payout account transaction", "errors": [ { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "reason": "Payments endpoints are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "reason": "Payments haven't been set up for your business yet." }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service failed to process the request." }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "reason": "A query parameter or field is invalid." }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "reason": "Unexpected error in the payments service." }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "reason": "The payments service couldn't complete the request. Try again later." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The transaction ID isn't a valid UUID." }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "reason": "No payout account transaction with this ID exists on your account." } ] }, { "operationId": "getV1WalletCryptoByCurrencyDepositAddress", "method": "GET", "path": "/v1/wallet/crypto/{currency}/deposit/address", "summary": "Get a crypto deposit address", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency or `destinationCurrency` isn't recognised, or `accountType` is blank or isn't `COLLECTIONS`, `FUNDING` or `PAYOUTS`." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "`networkType` wasn't sent and the currency can't be deposited on a blockchain, for example a fiat currency." }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "reason": "Your business has no account of the requested `accountType` set up for `destinationCurrency`." }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "code": -13104, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "httpStatus": 403, "message": "Deposit address is not supported in your region", "reason": "The account has no address for this currency and network yet, and crypto deposits are restricted for your business, so a new one can't be created." }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "code": -13105, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "httpStatus": 400, "message": "Deposit address is not supported for the specified currency and network type", "reason": "The account has no address for this currency and network yet, and deposits on this network are disabled or not supported for this currency." }, { "ref": "ErrorCodes.COULD_NOT_GET_RECEIVE_ADDRESS", "code": -30, "name": "COULD_NOT_GET_RECEIVE_ADDRESS", "httpStatus": 500, "message": "Could not get deposit address", "reason": "A new deposit address couldn't be created. Try again later." } ] }, { "operationId": "getV1WalletCryptoByCurrencyDepositHistory", "method": "GET", "path": "/v1/wallet/crypto/{currency}/deposit/history", "summary": "List crypto deposits for a currency", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ] }, { "operationId": "getV1WalletCryptoByCurrencyWithdraw", "method": "GET", "path": "/v1/wallet/crypto/{currency}/withdraw", "summary": "Get crypto withdrawal settings", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "`networkType` wasn't sent and the currency can't be withdrawn on a blockchain, for example a fiat currency." } ] }, { "operationId": "postV1WalletCryptoByCurrencyWithdraw", "method": "POST", "path": "/v1/wallet/crypto/{currency}/withdraw", "summary": "Withdraw crypto", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised, or the body fails validation, for example `amount` isn't a positive decimal, both or neither of `address` and `addressBookId` are sent, or the recipient's details are missing; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_NOT_FOUND", "code": -13422, "name": "ADDRESS_BOOK_ENTRY_NOT_FOUND", "httpStatus": 404, "message": "Could not find address book entry.", "reason": "No entry with this `addressBookId` exists in the account's address book." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "code": -13423, "name": "ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "httpStatus": 500, "message": "Address book entry not valid for specified currency", "reason": "The address-book entry is saved for a different currency." }, { "ref": "ErrorCodes.NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "code": -13427, "name": "NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "httpStatus": 400, "message": "Withdrawals to addresses not in your address book are disabled. Please contact support to change", "reason": "Withdrawals are restricted to address-book entries, and the address isn't saved in the account's address book." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "code": -13428, "name": "ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "httpStatus": 400, "message": "Address book entry too new. Withdrawals not allowed yet", "reason": "Withdrawals are restricted to address-book entries, and this entry was added or changed too recently. Try again once its waiting period has passed." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused after a recent security change on your account; the message says when they resume. Withdrawals to address-book entries may still be allowed." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are temporarily unavailable." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "The currency is under maintenance. Try again in a few minutes." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "The currency can't be withdrawn on a blockchain, for example a fiat currency." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "code": -13018, "name": "BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "httpStatus": 400, "message": "Unable to validate network type for provided currency", "reason": "The network isn't available for this currency." }, { "ref": "ErrorCodes.WITHDRAW_UNAVAILABLE", "code": -46, "name": "WITHDRAW_UNAVAILABLE", "httpStatus": 500, "message": "Withdrawal currently unavailable.", "reason": "Withdrawals of this currency on this network are currently disabled, or the withdrawal couldn't be recorded. Try again later." }, { "ref": "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "code": -13402, "name": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "httpStatus": 400, "message": "This currency does not support a payment reference field", "reason": "A `paymentReference` was sent, but this currency and network don't use one." }, { "ref": "ErrorCodes.PAYMENT_REFERENCE_MISSING", "code": -13410, "name": "PAYMENT_REFERENCE_MISSING", "httpStatus": 400, "message": "This withdrawal address requires a ", "reason": "The address needs a payment reference, such as a memo or tag; send it in `paymentReference`." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE", "code": -13405, "name": "INVALID_WITHDRAW_TRANSACTION_REFERENCE", "httpStatus": 400, "message": "Invalid transaction reference", "reason": "The `paymentReference` isn't valid for this network." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_ADDRESS", "code": -50, "name": "INVALID_WITHDRAW_ADDRESS", "httpStatus": 400, "message": "Invalid Withdraw address.", "reason": "The address isn't valid for this currency and network." }, { "ref": "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM", "code": -13411, "name": "WITHDRAW_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Please ensure withdrawal amount is larger than ", "reason": "The amount is below the network's minimum, which the message gives." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_AMOUNT", "code": -13404, "name": "INVALID_WITHDRAW_AMOUNT", "httpStatus": 400, "message": "Invalid withdraw amount, please ensure amount is larger than minimum", "reason": "The network rejected the amount, for example because it has too many decimal places." }, { "ref": "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "code": -13419, "name": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "httpStatus": 400, "message": "Withdrawals to this address are not allowed", "reason": "Sending to this address would need more network fee than is allowed, so it can't receive withdrawals." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "code": -13017, "name": "BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "httpStatus": 400, "message": "Unable to verify trustline. Please confirm that your address has an active trustline for this asset.", "reason": "The destination address has no active trustline for this asset." }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "code": -13019, "name": "BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "httpStatus": 400, "message": "Contact token issuer for whitelisting.", "reason": "The token issuer hasn't whitelisted the destination address." }, { "ref": "ErrorCodes.BLOCKCHAIN_SEND_FAILURE", "code": -29, "name": "BLOCKCHAIN_SEND_FAILURE", "httpStatus": 500, "message": "Unknown Blockchain Send Failure", "reason": "The withdrawal couldn't be checked with the network. Try again later." }, { "ref": "ApplicationErrorCodes.SERVICE_PROVIDER_NOT_FOUND", "code": -30071, "name": "SERVICE_PROVIDER_NOT_FOUND", "httpStatus": 400, "message": "Service provider not found.", "reason": "`serviceProviderId` isn't in the list from `GET /v1/wallet/crypto/service-providers`." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover the amount plus the network fee." }, { "ref": "ErrorCodes.WITHDRAW_LIMIT_REACHED", "code": -108, "name": "WITHDRAW_LIMIT_REACHED", "httpStatus": 400, "message": "Amount exceeds daily limit", "reason": "The withdrawal would exceed your business's withdrawal limit; see `GET /v1/wallet/crypto/{currency}/withdraw/limits`." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "Your business must keep a minimum portfolio value, and this withdrawal would take it below that." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` is `true`, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` is `true`, but borrowing for withdrawals is currently unavailable." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` is `true`, but this currency can't be borrowed for withdrawals." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` is `true`, but the amount can't be borrowed right now. Try again later." } ] }, { "operationId": "getV1WalletCryptoByCurrencyWithdrawById", "method": "GET", "path": "/v1/wallet/crypto/{currency}/withdraw/{id}", "summary": "Get a crypto withdrawal", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised or the withdrawal ID isn't a valid UUID." }, { "ref": "ErrorCodes.SEND_NOT_FOUND", "code": -13403, "name": "SEND_NOT_FOUND", "httpStatus": 404, "message": "Could not find send", "reason": "No withdrawal with this ID exists on the account, or it's in a different currency." } ] }, { "operationId": "getV1WalletCryptoByCurrencyWithdrawHistory", "method": "GET", "path": "/v1/wallet/crypto/{currency}/withdraw/history", "summary": "List crypto withdrawals for a currency", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ] }, { "operationId": "getV1WalletCryptoByCurrencyWithdrawLimits", "method": "GET", "path": "/v1/wallet/crypto/{currency}/withdraw/limits", "summary": "Get crypto withdrawal limits", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." } ] }, { "operationId": "getV1WalletCryptoAddressBook", "method": "GET", "path": "/v1/wallet/crypto/address-book", "summary": "List address-book entries", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank." } ] }, { "operationId": "getV1WalletCryptoAddressBookByCurrency", "method": "GET", "path": "/v1/wallet/crypto/address-book/{currency}", "summary": "List address-book entries for a currency", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised, `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank." } ] }, { "operationId": "getV1WalletCryptoDepositHistory", "method": "GET", "path": "/v1/wallet/crypto/deposit/history", "summary": "List crypto deposits", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ] }, { "operationId": "getV1WalletCryptoServiceProviders", "method": "GET", "path": "/v1/wallet/crypto/service-providers", "summary": "List service providers", "errors": [] }, { "operationId": "getV1WalletCryptoWithdrawHistory", "method": "GET", "path": "/v1/wallet/crypto/withdraw/history", "summary": "List crypto withdrawals", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised." } ] }, { "operationId": "getV1WalletFiatByCurrencyAccounts", "method": "GET", "path": "/v1/wallet/fiat/{currency}/accounts", "summary": "List bank accounts", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." } ] }, { "operationId": "postV1WalletFiatByCurrencyAccounts", "method": "POST", "path": "/v1/wallet/fiat/{currency}/accounts", "summary": "Link a bank account", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `bank` that isn't in the country's bank list or a branch code, account number or account type that doesn't fit the country, or the currency isn't recognised; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Withdrawals to this branch code aren't supported. Use another branch or contact support." }, { "ref": "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "code": -13418, "name": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "httpStatus": 400, "message": "Bank account linking has been temporarily suspended", "reason": "Linking bank accounts is paused for a while after a security change on your account, such as a password reset or a new device; the message says when it's re-enabled." }, { "ref": "ErrorCodes.INVALID_COUNTRY_ALPHA_2", "code": -115, "name": "INVALID_COUNTRY_ALPHA_2", "httpStatus": 400, "message": "Invalid country alpha 2", "reason": "No banks are available for the bank account's country." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list for the bank account's country couldn't be loaded. Try again later." } ] }, { "operationId": "deleteV1WalletFiatByCurrencyAccountsById", "method": "DELETE", "path": "/v1/wallet/fiat/{currency}/accounts/{id}", "summary": "Delete a bank account", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The bank account ID isn't a valid UUID, or the `Content-Type: application/json` header is missing." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID is linked to the account." } ] }, { "operationId": "getV1WalletFiatByCurrencyAccountsById", "method": "GET", "path": "/v1/wallet/fiat/{currency}/accounts/{id}", "summary": "Get a bank account", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised or the bank account ID isn't a valid UUID." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID is linked to the account." } ] }, { "operationId": "getV1WalletFiatByCurrencyBanks", "method": "GET", "path": "/v1/wallet/fiat/{currency}/banks", "summary": "List banks for a currency", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "reason": "Bank accounts can't be linked in this currency." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list couldn't be loaded. Try again later." } ] }, { "operationId": "getV1WalletFiatByCurrencyDepositReference", "method": "GET", "path": "/v1/wallet/fiat/{currency}/deposit/reference", "summary": "Get the account deposit reference", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." }, { "ref": "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "code": -15111, "name": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Deposits in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow deposits in this currency." } ] }, { "operationId": "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol", "method": "GET", "path": "/v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}", "summary": "Get an auto-buy deposit reference", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`currency` or `buyCurrencySymbol` isn't a recognised currency." }, { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "There's no market for buying `buyCurrencySymbol` with `currency`." }, { "ref": "ErrorCodes.CURRENCY_PAIR_NOT_ACTIVE", "code": -32, "name": "CURRENCY_PAIR_NOT_ACTIVE", "httpStatus": 400, "message": "The given currency pair is not active", "reason": "The market for buying `buyCurrencySymbol` with `currency` isn't active." }, { "ref": "ErrorCodes.CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15132, "name": "CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 400, "message": "Currency not enabled for Auto-Buy", "reason": "`buyCurrencySymbol` can't be auto-bought with `currency`; list the currencies that can with List auto-buy currencies." }, { "ref": "ErrorCodes.CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15134, "name": "CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 451, "message": "Auto-buys in the selected currency are not supported in your region", "reason": "Auto-buy into `buyCurrencySymbol` with `currency` isn't available for your business." }, { "ref": "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "code": -15111, "name": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Deposits in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow deposits in `currency`." } ] }, { "operationId": "getV1WalletFiatByCurrencyAutoBuy", "method": "GET", "path": "/v1/wallet/fiat/{currency}/auto-buy", "summary": "List auto-buy currencies", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The currency isn't recognised." } ] }, { "operationId": "getV1WalletFiatByCurrencyWithdrawEstimateFee", "method": "GET", "path": "/v1/wallet/fiat/{currency}/withdraw/estimate-fee", "summary": "Estimate a fiat withdrawal fee", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`linkedBankAccountId` is missing or isn't a UUID, `amount` is missing or isn't a number, `fast` isn't `true` or `false`, or the currency isn't recognised." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with this ID exists." } ] }, { "operationId": "postV1WalletFiatByCurrencyWithdraw", "method": "POST", "path": "/v1/wallet/fiat/{currency}/withdraw", "summary": "Withdraw fiat to a bank account", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, or `reference` was rejected, or the currency isn't recognised; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The withdrawal would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with `linkedBankAccountId` exists." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Withdrawals to the bank account's branch code aren't supported. Use another bank account or contact support." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "code": -15307, "name": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Amount is lower than the minimum", "reason": "`amount` is below the minimum withdrawal for this currency." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "code": -15318, "name": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "httpStatus": 400, "message": "Withdrawal currency does not match the currency of selected bank account", "reason": "The bank account was linked for a different currency." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the fee." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "code": -15322, "name": "CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account has been deleted. Please add the account and try again.", "reason": "The bank account has been deleted. Link it again to withdraw to it." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "code": -15321, "name": "CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not confirmed. Please complete our verification process to withdraw.", "reason": "The bank account was never confirmed." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "code": -15309, "name": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not verified. Please withdraw to a verified account.", "reason": "This currency only pays out to verified bank accounts, and this one hasn't been verified yet or failed verification." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` was set, but this currency can't be borrowed for a withdrawal." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` was set, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` was set, but the amount to borrow isn't available right now. Try again later." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's total borrow limit." } ] }, { "operationId": "getV1WalletFiatByCurrencyWithdrawals", "method": "GET", "path": "/v1/wallet/fiat/{currency}/withdrawals", "summary": "List fiat withdrawals", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`status` is empty or isn't one of the listed values, `limit` or `offset` isn't a whole number, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised." } ] }, { "operationId": "getV1WalletFiatByCurrencyWithdrawalsById", "method": "GET", "path": "/v1/wallet/fiat/{currency}/withdrawals/{id}", "summary": "Get a fiat withdrawal", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The withdrawal ID isn't a valid UUID, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised." }, { "ref": "ErrorCodes.COULD_NOT_FIND_FIAT_WITHDRAWAL", "code": -15300, "name": "COULD_NOT_FIND_FIAT_WITHDRAWAL", "httpStatus": 404, "message": "The requested withdrawal does not exist", "reason": "No withdrawal in this currency with this ID exists on the account, or on any of your business's visible accounts when `includeAllSubAccounts` applies." } ] }, { "operationId": "postV2FiatPayments", "method": "POST", "path": "/v2/fiat/payments", "summary": "Pay a bank beneficiary", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `newBeneficiary` field or a `newBeneficiary.bank` that isn't in the country's bank list, or `reference` was rejected; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_API_DISABLED", "code": -18106, "name": "PAYMENTS_API_DISABLED", "httpStatus": 404, "message": "API payments are not enabled.", "reason": "This endpoint isn't available yet." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currency` isn't a recognised currency." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "code": -18104, "name": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "httpStatus": 400, "message": "Provide either an existing beneficiary id or full beneficiary details.", "reason": "Neither `beneficiaryId` nor `newBeneficiary` was sent." }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "reason": "No bank account with `beneficiaryId` exists." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE", "code": -18103, "name": "PAYMENT_BENEFICIARY_NOT_ACTIVE", "httpStatus": 409, "message": "The selected payment beneficiary is not active.", "reason": "The beneficiary with `beneficiaryId` was never confirmed or has been deleted." }, { "ref": "ErrorCodes.INVALID_COUNTRY_ALPHA_2", "code": -115, "name": "INVALID_COUNTRY_ALPHA_2", "httpStatus": 400, "message": "Invalid country alpha 2", "reason": "No banks are available for `newBeneficiary`'s country." }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "reason": "The bank list for `newBeneficiary`'s country couldn't be loaded. Try again later." }, { "ref": "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "code": -13418, "name": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "httpStatus": 400, "message": "Bank account linking has been temporarily suspended", "reason": "Adding a beneficiary is paused for a while after a security change on your account; the message says when it's re-enabled. You can still pay an existing beneficiary." }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "reason": "Payments to the beneficiary's branch code aren't supported. Use another bank account or contact support." }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "reason": "Your business's region doesn't allow withdrawals in this currency." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The payment would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "code": -15307, "name": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Amount is lower than the minimum", "reason": "`amount` is below the minimum withdrawal for this currency." }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "code": -15318, "name": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "httpStatus": 400, "message": "Withdrawal currency does not match the currency of selected bank account", "reason": "The beneficiary's bank account was linked for a different currency from `currency`." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the fee." }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "code": -15309, "name": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not verified. Please withdraw to a verified account.", "reason": "This currency only pays out to verified bank accounts, and the beneficiary hasn't been verified yet or failed verification." } ] }, { "operationId": "postV2CryptoPayments", "method": "POST", "path": "/v2/crypto/payments", "summary": "Pay a crypto beneficiary", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation, including a `newBeneficiary` field or missing travel-rule details (`beneficiaryName`, `isCorporate`, `isSelfHosted`, and a service provider for a hosted wallet) for an address outside VALR; `validationErrors` lists each failing field." }, { "ref": "ApplicationErrorCodes.PAYMENTS_API_DISABLED", "code": -18106, "name": "PAYMENTS_API_DISABLED", "httpStatus": 404, "message": "API payments are not enabled.", "reason": "This endpoint isn't available yet." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currency` isn't a recognised currency." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "code": -18104, "name": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "httpStatus": 400, "message": "Provide either an existing beneficiary id or full beneficiary details.", "reason": "Neither `beneficiaryId` nor `newBeneficiary` was sent." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_FOUND", "code": -18101, "name": "PAYMENT_BENEFICIARY_NOT_FOUND", "httpStatus": 404, "message": "Payment beneficiary not found.", "reason": "No address-book entry with `beneficiaryId` exists on the account." }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE", "code": -18103, "name": "PAYMENT_BENEFICIARY_NOT_ACTIVE", "httpStatus": 409, "message": "The selected payment beneficiary is not active.", "reason": "The address-book entry with `beneficiaryId` hasn't been activated." }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "code": -13426, "name": "ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "httpStatus": 400, "message": "The label provided is already in use.", "reason": "Another address-book entry on the account already uses `newBeneficiary.label`." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_ADDRESS", "code": -50, "name": "INVALID_WITHDRAW_ADDRESS", "httpStatus": 400, "message": "Invalid Withdraw address.", "reason": "The beneficiary's address isn't valid for this currency and network." }, { "ref": "ErrorCodes.PAYMENT_REFERENCE_MISSING", "code": -13410, "name": "PAYMENT_REFERENCE_MISSING", "httpStatus": 400, "message": "This withdrawal address requires a ", "reason": "The beneficiary's address needs a payment reference, such as a memo or tag." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE", "code": -13405, "name": "INVALID_WITHDRAW_TRANSACTION_REFERENCE", "httpStatus": 400, "message": "Invalid transaction reference", "reason": "The beneficiary's payment reference isn't valid for this address." }, { "ref": "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "code": -13402, "name": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "httpStatus": 400, "message": "This currency does not support a payment reference field", "reason": "The beneficiary has a payment reference, but this currency and network don't use one." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "Withdrawals of this currency are paused for maintenance. Try again in a few minutes." }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "reason": "Withdrawals are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "reason": "Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled." }, { "ref": "ErrorCodes.WITHDRAW_UNAVAILABLE", "code": -46, "name": "WITHDRAW_UNAVAILABLE", "httpStatus": 500, "message": "Withdrawal currently unavailable.", "reason": "Withdrawals of this currency on this network are unavailable at the moment. Try again later." }, { "ref": "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM", "code": -13411, "name": "WITHDRAW_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Please ensure withdrawal amount is larger than ", "reason": "`amount` is below the minimum withdrawal for this currency and network." }, { "ref": "ErrorCodes.INVALID_WITHDRAW_AMOUNT", "code": -13404, "name": "INVALID_WITHDRAW_AMOUNT", "httpStatus": 400, "message": "Invalid withdraw amount, please ensure amount is larger than minimum", "reason": "`amount` isn't valid for this currency and network, for example it has too many decimal places." }, { "ref": "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "code": -13419, "name": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "httpStatus": 400, "message": "Withdrawals to this address are not allowed", "reason": "Withdrawals to the beneficiary's address aren't allowed because sending to it would cost too much in network fees." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "The account's available balance doesn't cover `amount` plus the network fee." }, { "ref": "ErrorCodes.WITHDRAW_LIMIT_REACHED", "code": -108, "name": "WITHDRAW_LIMIT_REACHED", "httpStatus": 400, "message": "Amount exceeds daily limit", "reason": "The payment would exceed your daily withdrawal limit." }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "reason": "The payment would take your portfolio below the minimum value it must keep." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "`allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "`allowBorrow` was set, but this currency can't be borrowed for a withdrawal." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` was set, but margin isn't enabled on the account." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "`allowBorrow` was set, but the amount to borrow isn't available right now. Try again later." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would exceed the account's total borrow limit." } ] }, { "operationId": "getV1AccountTransactionhistory", "method": "GET", "path": "/v1/account/transactionhistory", "summary": "List transactions", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime`, `currency` isn't a currency VALR supports, `transactionTypes` contains an unknown type, or `beforeId` isn't a valid UUID." } ] }, { "operationId": "getV1AccountTransactionhistorySubaccounts", "method": "GET", "path": "/v1/account/transactionhistory/subaccounts", "summary": "List transactions for all sub-accounts", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`beforeId` was sent (it isn't supported here), `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime` or more than 7 days after it, `currency` isn't a currency VALR supports, or `transactionTypes` contains an unknown type." } ] }, { "operationId": "getV1AccountBalancesAll", "method": "GET", "path": "/v1/account/balances/all", "summary": "Get balances for all accounts", "errors": [] }, { "operationId": "getV1AccountSubaccounts", "method": "GET", "path": "/v1/account/subaccounts", "summary": "List sub-accounts", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`includeTags` or `includePayoutAccounts` isn't `true` or `false`." } ] }, { "operationId": "getV1AccountSubaccountByAccountPublicId", "method": "GET", "path": "/v1/account/subaccount/{accountPublicId}", "summary": "Get a sub-account", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The sub-account ID isn't a whole number." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this ID. Your primary account (`0`) isn't a sub-account." } ] }, { "operationId": "postV1AccountSubaccount", "method": "POST", "path": "/v1/account/subaccount", "summary": "Create a sub-account", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS", "code": -11132, "name": "SUB_ACCOUNT_ALREADY_EXISTS", "httpStatus": 403, "message": "A subaccount with that label already exists", "reason": "Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_LIMIT_EXCEEDED", "code": -11136, "name": "SUB_ACCOUNT_LIMIT_EXCEEDED", "httpStatus": 403, "message": "New subaccount limit exceeded", "reason": "Your business already has the maximum number of sub-accounts." }, { "ref": "ApplicationErrorCodes.INVALID_ACCOUNT_TAG_COMBINATION", "code": -17214, "name": "INVALID_ACCOUNT_TAG_COMBINATION", "httpStatus": 400, "message": "Invalid account tag combination", "reason": "`accountTags` contains a tag other than `CLIENT_FUNDS`." }, { "ref": "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "code": -11423, "name": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "httpStatus": 409, "message": "Sub account with Id, E-mail or Cell number already exists", "reason": "Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number." } ] }, { "operationId": "putV1AccountSubaccount", "method": "PUT", "path": "/v1/account/subaccount", "summary": "Rename a sub-account", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this `id`." }, { "ref": "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS", "code": -11132, "name": "SUB_ACCOUNT_ALREADY_EXISTS", "httpStatus": 403, "message": "A subaccount with that label already exists", "reason": "Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`." }, { "ref": "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "code": -11423, "name": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "httpStatus": 409, "message": "Sub account with Id, E-mail or Cell number already exists", "reason": "Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number." } ] }, { "operationId": "deleteV1AccountSubaccount", "method": "DELETE", "path": "/v1/account/subaccount", "summary": "Delete a sub-account", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "reason": "None of your business's sub-accounts has this `id`." }, { "ref": "ErrorCodes.CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "code": -11163, "name": "CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "httpStatus": 400, "message": "Cannot disable sub account with balances", "reason": "The sub-account still holds funds, reserved amounts or debt. Cancel its open orders, transfer its funds out and repay any borrowing, then try again." }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "code": -17217, "name": "CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable a system-provisioned sub account", "reason": "VALR set this sub-account up for you, so it can't be deleted." }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "code": -17216, "name": "CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable shared sub account", "reason": "The sub-account is shared with another VALR user. Stop sharing it, then try again." } ] }, { "operationId": "postV1AccountSubaccountsTransfer", "method": "POST", "path": "/v1/account/subaccounts/transfer", "summary": "Transfer between accounts", "errors": [ { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "reason": "The body isn't valid JSON." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "The body is empty or a field fails validation; `validationErrors` lists each failing field." }, { "ref": "ErrorCodes.SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "code": -11133, "name": "SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "httpStatus": 403, "message": "Internal transfer did not succeed", "reason": "The transfer was refused, and the message says why: `fromId` and `toId` are the same, one of them isn't an account in your business, the source account doesn't have enough available balance and `allowBorrow` is `false`, you called it on a sub-account and `fromId` isn't that sub-account, or your key is limited to sub-accounts and one of the accounts isn't among them." }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "reason": "`currencyCode` isn't a currency VALR supports." }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "reason": "`allowBorrow` is `true`, but the source account isn't enabled for margin." }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "reason": "`allowBorrow` is `true`, but the source account doesn't have enough collateral to borrow the shortfall." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "reason": "Borrowing for transfers is temporarily unavailable. Transfer no more than the available balance, or try again later." }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "reason": "This currency can't be borrowed for a transfer." }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would take the source account past its borrow limit for this currency." }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "reason": "Borrowing the shortfall would take the source account past its total borrow limit." }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "reason": "Not enough of this currency is available to borrow right now. Try again later." }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "reason": "The currency is under maintenance. Try again in a few minutes." }, { "ref": "ApplicationErrorCodes.INTERNAL_TRANSFERS_NOT_AVAILABLE", "code": -11652, "name": "INTERNAL_TRANSFERS_NOT_AVAILABLE", "httpStatus": 503, "message": "Internal transfers are currently not available.", "reason": "Transfers between accounts are temporarily unavailable." } ] }, { "operationId": "getV1PublicTime", "method": "GET", "path": "/v1/public/time", "summary": "Get the server time", "errors": [] }, { "operationId": "getV1PublicStatus", "method": "GET", "path": "/v1/public/status", "summary": "Get the exchange status", "errors": [] }, { "operationId": "getV1PublicMarketsummary", "method": "GET", "path": "/v1/public/marketsummary", "summary": "List market summaries", "errors": [] }, { "operationId": "getV1PublicByCurrencyPairMarketsummary", "method": "GET", "path": "/v1/public/{currencyPair}/marketsummary", "summary": "Get a pair's market summary", "errors": [ { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "`currencyPair` isn't a currency pair VALR supports." }, { "ref": "ErrorCodes.MARKET_SUMMARY_NOT_FOUND", "code": -111, "name": "MARKET_SUMMARY_NOT_FOUND", "httpStatus": 404, "message": "Market summary not found", "reason": "VALR has no market summary for the pair yet, which can happen for a pair that isn't trading." } ] }, { "operationId": "getV1PublicByCurrencyPairBuckets", "method": "GET", "path": "/v1/public/{currencyPair}/buckets", "summary": "List price buckets", "errors": [ { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "reason": "`currencyPair` isn't a currency pair VALR supports." }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`periodSeconds` isn't one of the supported periods, `skip` or `limit` isn't a whole number, `limit` is more than 400, or `includeEmpty` isn't `true` or `false`." } ] }, { "operationId": "getV1PublicCurrencies", "method": "GET", "path": "/v1/public/currencies", "summary": "List currencies", "errors": [] }, { "operationId": "getV1PublicPairs", "method": "GET", "path": "/v1/public/pairs", "summary": "List currency pairs", "errors": [] }, { "operationId": "getV1PublicPairsByType", "method": "GET", "path": "/v1/public/pairs/{type}", "summary": "List currency pairs by type", "errors": [ { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "reason": "`type` isn't `SPOT` or `FUTURE`." } ] } ], "index": [ { "ref": "ErrorCodes.WITHDRAW_LIMIT_REACHED", "code": -108, "name": "WITHDRAW_LIMIT_REACHED", "httpStatus": 400, "message": "Amount exceeds daily limit", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.INVALID_CURRENCY_SYMBOL", "code": -109, "name": "INVALID_CURRENCY_SYMBOL", "httpStatus": 400, "message": "Invalid currency symbol", "operations": [ "postV2FiatPayments", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.INVALID_REQUEST", "code": -11, "name": "INVALID_REQUEST", "httpStatus": 400, "message": "Invalid Request, please check your request and try again", "operations": [ "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "postV2WalletFiatByCurrencyPaymentReferences", "getV2WalletFiatByCurrencyPaymentReferences", "getV2PaymentsBulkWithdrawalsBatchesById", "postV1Webhooks", "deleteV1WebhooksById", "getV1WebhooksById", "putV1WebhooksById", "getV1WebhooksByIdDeliveries", "getV1WebhooksByIdEventsByEventId", "postV2WalletFiatByCurrencyPaymentBulkReferences", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems", "getV2WalletFiatByCurrencyPaymentDeposits", "deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "getV2PaymentsById", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsAccountBalancesByType", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsPayoutHistoryById", "getV1WalletCryptoByCurrencyDepositAddress", "getV1WalletCryptoByCurrencyDepositHistory", "getV1WalletCryptoByCurrencyWithdraw", "postV1WalletCryptoByCurrencyWithdraw", "getV1WalletCryptoByCurrencyWithdrawById", "getV1WalletCryptoByCurrencyWithdrawHistory", "getV1WalletCryptoByCurrencyWithdrawLimits", "getV1WalletCryptoAddressBook", "getV1WalletCryptoAddressBookByCurrency", "getV1WalletCryptoDepositHistory", "getV1WalletCryptoWithdrawHistory", "getV1WalletFiatByCurrencyAccounts", "postV1WalletFiatByCurrencyAccounts", "deleteV1WalletFiatByCurrencyAccountsById", "getV1WalletFiatByCurrencyAccountsById", "getV1WalletFiatByCurrencyBanks", "getV1WalletFiatByCurrencyDepositReference", "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol", "getV1WalletFiatByCurrencyAutoBuy", "getV1WalletFiatByCurrencyWithdrawEstimateFee", "postV1WalletFiatByCurrencyWithdraw", "getV1WalletFiatByCurrencyWithdrawals", "getV1WalletFiatByCurrencyWithdrawalsById", "postV2FiatPayments", "postV2CryptoPayments", "getV1AccountTransactionhistory", "getV1AccountTransactionhistorySubaccounts", "getV1AccountSubaccounts", "getV1AccountSubaccountByAccountPublicId", "postV1AccountSubaccount", "putV1AccountSubaccount", "deleteV1AccountSubaccount", "postV1AccountSubaccountsTransfer", "getV1PublicByCurrencyPairBuckets", "getV1PublicPairsByType" ] }, { "ref": "ErrorCodes.SUB_ACCOUNT_NOT_FOUND", "code": -11134, "name": "SUB_ACCOUNT_NOT_FOUND", "httpStatus": 400, "message": "Subaccount not found", "operations": [ "getV1AccountSubaccountByAccountPublicId", "putV1AccountSubaccount", "deleteV1AccountSubaccount" ] }, { "ref": "ErrorCodes.CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "code": -11163, "name": "CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES", "httpStatus": 400, "message": "Cannot disable sub account with balances", "operations": [ "deleteV1AccountSubaccount" ] }, { "ref": "ErrorCodes.CURRENCY_NOT_SUPPORTED", "code": -112, "name": "CURRENCY_NOT_SUPPORTED", "httpStatus": 400, "message": "Currency not supported", "operations": [ "getV1WalletCryptoByCurrencyDepositAddress", "getV1WalletCryptoByCurrencyWithdraw", "postV1WalletCryptoByCurrencyWithdraw", "getV1WalletFiatByCurrencyBanks" ] }, { "ref": "ApplicationErrorCodes.API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "code": -11258, "name": "API_KEY_REQUEST_TIMESTAMP_TOO_EARLY", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "operations": [], "allOperations": true }, { "ref": "ApplicationErrorCodes.API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "code": -11259, "name": "API_KEY_MESSAGE_TIMESTAMP_EXPIRED", "httpStatus": 400, "message": "Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past", "messageVaries": true, "operations": [], "allOperations": true }, { "ref": "ErrorCodes.API_KEY_API_KEY_HEADER_MISSING", "code": -11268, "name": "API_KEY_API_KEY_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-API-KEY", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.API_KEY_SIGNATURE_HEADER_MISSING", "code": -11269, "name": "API_KEY_SIGNATURE_HEADER_MISSING", "httpStatus": 400, "message": "API key header missing: X-VALR-SIGNATURE", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "code": -11270, "name": "API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID", "httpStatus": 400, "message": "API key header missing or is invalid: X-VALR-TIMESTAMP", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.INVALID_JSON", "code": -113, "name": "INVALID_JSON", "httpStatus": 400, "message": "Invalid JSON payload", "operations": [ "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "postV2WalletFiatByCurrencyPaymentReferences", "postV1Webhooks", "putV1WebhooksById", "postV2WalletFiatByCurrencyPaymentBulkReferences", "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "postV2PaymentsBulkWithdrawalsBatches", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "postV2PaymentsBulkWithdrawalsBeneficiaries", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyAccounts", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments", "postV2CryptoPayments", "postV1AccountSubaccount", "putV1AccountSubaccount", "deleteV1AccountSubaccount", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.INVALID_COUNTRY_ALPHA_2", "code": -115, "name": "INVALID_COUNTRY_ALPHA_2", "httpStatus": 400, "message": "Invalid country alpha 2", "operations": [ "postV1WalletFiatByCurrencyAccounts", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11533, "name": "CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account borrow limit for requested currency would be exceeded and is therefore not allowed.", "operations": [ "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "code": -11534, "name": "ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING", "httpStatus": 400, "message": "Account total borrow limit would be exceeded and is therefore not allowed.", "operations": [ "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "code": -13017, "name": "BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID", "httpStatus": 400, "message": "Unable to verify trustline. Please confirm that your address has an active trustline for this asset.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "code": -13018, "name": "BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY", "httpStatus": 400, "message": "Unable to validate network type for provided currency", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ApplicationErrorCodes.BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "code": -13019, "name": "BLOCKCHAIN_SEND_MISSING_KYC_PERMIT", "httpStatus": 400, "message": "Contact token issuer for whitelisting.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "code": -13105, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE", "httpStatus": 400, "message": "Deposit address is not supported for the specified currency and network type", "operations": [ "getV1WalletCryptoByCurrencyDepositAddress" ] }, { "ref": "ErrorCodes.CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "code": -13402, "name": "CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE", "httpStatus": 400, "message": "This currency does not support a payment reference field", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.INVALID_WITHDRAW_AMOUNT", "code": -13404, "name": "INVALID_WITHDRAW_AMOUNT", "httpStatus": 400, "message": "Invalid withdraw amount, please ensure amount is larger than minimum", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.INVALID_WITHDRAW_TRANSACTION_REFERENCE", "code": -13405, "name": "INVALID_WITHDRAW_TRANSACTION_REFERENCE", "httpStatus": 400, "message": "Invalid transaction reference", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.PAYMENT_REFERENCE_MISSING", "code": -13410, "name": "PAYMENT_REFERENCE_MISSING", "httpStatus": 400, "message": "This withdrawal address requires a ", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.WITHDRAW_AMOUNT_BELOW_MINIMUM", "code": -13411, "name": "WITHDRAW_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Please ensure withdrawal amount is larger than ", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.WITHDRAWALS_TEMPORARILY_SUSPENDED", "code": -13415, "name": "WITHDRAWALS_TEMPORARILY_SUSPENDED", "httpStatus": 400, "message": "Withdrawals have been suspended", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "code": -13418, "name": "BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED", "httpStatus": 400, "message": "Bank account linking has been temporarily suspended", "operations": [ "postV1WalletFiatByCurrencyAccounts", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "code": -13419, "name": "NETWORK_FEE_FOR_TRANSACTION_EXCEEDED", "httpStatus": 400, "message": "Withdrawals to this address are not allowed", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "code": -13426, "name": "ADDRESS_BOOK_ENTRY_LABEL_IN_USE", "httpStatus": 400, "message": "The label provided is already in use.", "operations": [ "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "code": -13427, "name": "NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED", "httpStatus": 400, "message": "Withdrawals to addresses not in your address book are disabled. Please contact support to change", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "code": -13428, "name": "ADDRESS_BOOK_ENTRY_STILL_WARMING_UP", "httpStatus": 400, "message": "Address book entry too new. Withdrawals not allowed yet", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "code": -15115, "name": "UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE", "httpStatus": 400, "message": "Deposit override is invalid", "operations": [ "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference" ] }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "code": -15121, "name": "BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE", "httpStatus": 400, "message": "Batch size exceeds maximum allowed", "operations": [ "postV2WalletFiatByCurrencyPaymentBulkReferences" ] }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "code": -15123, "name": "BULK_DEPOSIT_REFERENCE_INVALID_SENDER", "httpStatus": 400, "message": "Invalid sender information", "operations": [ "postV2WalletFiatByCurrencyPaymentBulkReferences" ] }, { "ref": "ErrorCodes.CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15132, "name": "CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 400, "message": "Currency not enabled for Auto-Buy", "operations": [ "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol" ] }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "code": -15307, "name": "FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM", "httpStatus": 400, "message": "Amount is lower than the minimum", "operations": [ "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "code": -15309, "name": "CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not verified. Please withdraw to a verified account.", "operations": [ "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "code": -15318, "name": "FIAT_WITHDRAWAL_CURRENCY_MISMATCH", "httpStatus": 400, "message": "Withdrawal currency does not match the currency of selected bank account", "operations": [ "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "code": -15321, "name": "CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account is not confirmed. Please complete our verification process to withdraw.", "operations": [ "postV1WalletFiatByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "code": -15322, "name": "CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT", "httpStatus": 400, "message": "This bank account has been deleted. Please add the account and try again.", "operations": [ "postV1WalletFiatByCurrencyWithdraw" ] }, { "ref": "ApplicationErrorCodes.SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "code": -15721, "name": "SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH", "httpStatus": 400, "message": "No scoped deposit account exists for the requested currency.", "operations": [ "postV2WalletFiatByCurrencyPaymentReferences", "getV2WalletFiatByCurrencyPaymentReferences", "postV2WalletFiatByCurrencyPaymentBulkReferences", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems", "getV2WalletFiatByCurrencyPaymentDeposits", "getV1WalletCryptoByCurrencyDepositAddress" ] }, { "ref": "ApplicationErrorCodes.FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "code": -15875, "name": "FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED", "httpStatus": 400, "message": "Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support.", "operations": [ "postV1WalletFiatByCurrencyAccounts", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ApplicationErrorCodes.INVALID_ACCOUNT_TAG_COMBINATION", "code": -17214, "name": "INVALID_ACCOUNT_TAG_COMBINATION", "httpStatus": 400, "message": "Invalid account tag combination", "operations": [ "postV1AccountSubaccount" ] }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "code": -17216, "name": "CANNOT_DISABLE_SHARED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable shared sub account", "operations": [ "deleteV1AccountSubaccount" ] }, { "ref": "ApplicationErrorCodes.CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "code": -17217, "name": "CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT", "httpStatus": 400, "message": "Cannot disable a system-provisioned sub account", "operations": [ "deleteV1AccountSubaccount" ] }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "code": -18104, "name": "PAYMENT_BENEFICIARY_DETAILS_REQUIRED", "httpStatus": 400, "message": "Provide either an existing beneficiary id or full beneficiary details.", "operations": [ "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "code": -18122, "name": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "httpStatus": 400, "message": "Webhook subscription limit reached:", "operations": [ "postV1Webhooks" ] }, { "ref": "ErrorCodes.MARGIN_NOT_ENABLED_FOR_ACCOUNT", "code": -19213, "name": "MARGIN_NOT_ENABLED_FOR_ACCOUNT", "httpStatus": 400, "message": "Margin not enabled for account", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "code": -19243, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "code": -19244, "name": "BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY", "httpStatus": 400, "message": "Borrowing for withdrawal and internal transfers currently not available for selected currency", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.INVALID_CURRENCY_PAIR", "code": -21, "name": "INVALID_CURRENCY_PAIR", "httpStatus": 400, "message": "Unsupported Currency Pair", "operations": [ "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol", "getV1PublicByCurrencyPairMarketsummary", "getV1PublicByCurrencyPairBuckets" ] }, { "ref": "ApplicationErrorCodes.SERVICE_PROVIDER_NOT_FOUND", "code": -30071, "name": "SERVICE_PROVIDER_NOT_FOUND", "httpStatus": 400, "message": "Service provider not found.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.CURRENCY_PAIR_NOT_ACTIVE", "code": -32, "name": "CURRENCY_PAIR_NOT_ACTIVE", "httpStatus": 400, "message": "The given currency pair is not active", "operations": [ "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol" ] }, { "ref": "ApplicationErrorCodes.WITHDRAWAL_RESTRICTION_APPLIED", "code": -32765, "name": "WITHDRAWAL_RESTRICTION_APPLIED", "httpStatus": 400, "message": "Withdrawal denied. Minimum portfolio value would not be met after this withdrawal.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.INVALID_WITHDRAW_ADDRESS", "code": -50, "name": "INVALID_WITHDRAW_ADDRESS", "httpStatus": 400, "message": "Invalid Withdraw address.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "ErrorCodes.INSUFFICIENT_BALANCE", "code": -6, "name": "INSUFFICIENT_BALANCE", "httpStatus": 400, "message": "Insufficient Balance", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "PaymentsErrorCode.BAD_REQUEST", "code": "BAD_REQUEST", "name": "BAD_REQUEST", "httpStatus": 400, "message": "Bad request.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "ErrorCodes.API_KEY_INVALID_SIGNATURE", "code": -11252, "name": "API_KEY_INVALID_SIGNATURE", "httpStatus": 401, "message": "Request has an invalid signature", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.API_KEY_INVALID", "code": -11264, "name": "API_KEY_INVALID", "httpStatus": 401, "message": "API key or secret is invalid", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.API_KEY_IP_NOT_WHITELISTED", "code": -11272, "name": "API_KEY_IP_NOT_WHITELISTED", "httpStatus": 401, "message": "The originating IP Address has not been whitelisted.", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.UNAUTHORIZED", "code": -93, "name": "UNAUTHORIZED", "httpStatus": 401, "message": "Unauthorized", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.SUB_ACCOUNT_ALREADY_EXISTS", "code": -11132, "name": "SUB_ACCOUNT_ALREADY_EXISTS", "httpStatus": 403, "message": "A subaccount with that label already exists", "operations": [ "postV1AccountSubaccount", "putV1AccountSubaccount" ] }, { "ref": "ErrorCodes.SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "code": -11133, "name": "SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED", "httpStatus": 403, "message": "Internal transfer did not succeed", "operations": [ "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.SUB_ACCOUNT_LIMIT_EXCEEDED", "code": -11136, "name": "SUB_ACCOUNT_LIMIT_EXCEEDED", "httpStatus": 403, "message": "New subaccount limit exceeded", "operations": [ "postV1AccountSubaccount" ] }, { "ref": "ApplicationErrorCodes.API_KEY_ENDPOINT_NOT_ALLOWED", "code": -11277, "name": "API_KEY_ENDPOINT_NOT_ALLOWED", "httpStatus": 403, "message": "This API key does not have permission to access this endpoint", "operations": [], "allOperations": true }, { "ref": "ApplicationErrorCodes.RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "code": -13104, "name": "RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION", "httpStatus": 403, "message": "Deposit address is not supported in your region", "operations": [ "getV1WalletCryptoByCurrencyDepositAddress" ] }, { "ref": "ApplicationErrorCodes.PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "code": -16098, "name": "PAYMENTS_USER_ACCESS_NOT_CONFIGURED", "httpStatus": 403, "message": "Payments access is not configured for this user.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "ErrorCodes.MARKET_SUMMARY_NOT_FOUND", "code": -111, "name": "MARKET_SUMMARY_NOT_FOUND", "httpStatus": 404, "message": "Market summary not found", "operations": [ "getV1PublicByCurrencyPairMarketsummary" ] }, { "ref": "ErrorCodes.SEND_NOT_FOUND", "code": -13403, "name": "SEND_NOT_FOUND", "httpStatus": 404, "message": "Could not find send", "operations": [ "getV1WalletCryptoByCurrencyWithdrawById" ] }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_NOT_FOUND", "code": -13422, "name": "ADDRESS_BOOK_ENTRY_NOT_FOUND", "httpStatus": 404, "message": "Could not find address book entry.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.COULD_NOT_GET_LINKED_ACCOUNT", "code": -14203, "name": "COULD_NOT_GET_LINKED_ACCOUNT", "httpStatus": 404, "message": "The requested bank account does not exist", "operations": [ "deleteV1WalletFiatByCurrencyAccountsById", "getV1WalletFiatByCurrencyAccountsById", "getV1WalletFiatByCurrencyWithdrawEstimateFee", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "code": -15114, "name": "UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND", "httpStatus": 404, "message": "Deposit reference not found", "operations": [ "getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference" ] }, { "ref": "ApplicationErrorCodes.FIAT_DEPOSIT_NOT_FOUND", "code": -15118, "name": "FIAT_DEPOSIT_NOT_FOUND", "httpStatus": 404, "message": "Deposit not found", "operations": [ "deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference", "putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference" ] }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "code": -15122, "name": "BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND", "httpStatus": 404, "message": "Bulk deposit job not found", "operations": [ "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems" ] }, { "ref": "ErrorCodes.COULD_NOT_FIND_FIAT_WITHDRAWAL", "code": -15300, "name": "COULD_NOT_FIND_FIAT_WITHDRAWAL", "httpStatus": 404, "message": "The requested withdrawal does not exist", "operations": [ "getV1WalletFiatByCurrencyWithdrawalsById" ] }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_FOUND", "code": -18101, "name": "PAYMENT_BENEFICIARY_NOT_FOUND", "httpStatus": 404, "message": "Payment beneficiary not found.", "operations": [ "postV2CryptoPayments" ] }, { "ref": "ApplicationErrorCodes.PAYMENTS_API_DISABLED", "code": -18106, "name": "PAYMENTS_API_DISABLED", "httpStatus": 404, "message": "API payments are not enabled.", "operations": [ "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "ApplicationErrorCodes.WEBHOOK_SUBSCRIPTION_NOT_FOUND", "code": -18121, "name": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "httpStatus": 404, "message": "Webhook subscription not found", "operations": [ "deleteV1WebhooksById", "getV1WebhooksById", "putV1WebhooksById", "getV1WebhooksByIdDeliveries", "getV1WebhooksByIdEventsByEventId" ] }, { "ref": "ApplicationErrorCodes.WEBHOOK_EVENT_NOT_FOUND", "code": -18123, "name": "WEBHOOK_EVENT_NOT_FOUND", "httpStatus": 404, "message": "Webhook event not found", "operations": [ "getV1WebhooksByIdEventsByEventId" ] }, { "ref": "PaymentsErrorCode.NOT_FOUND", "code": "NOT_FOUND", "name": "NOT_FOUND", "httpStatus": 404, "message": "Resource not found.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2PaymentsById", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsAccountBalancesByType", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "ApplicationErrorCodes.SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "code": -11423, "name": "SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS", "httpStatus": 409, "message": "Sub account with Id, E-mail or Cell number already exists", "operations": [ "postV1AccountSubaccount", "putV1AccountSubaccount" ] }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "code": -15124, "name": "BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS", "httpStatus": 409, "message": "A bulk deposit job is already being processed", "operations": [ "postV2WalletFiatByCurrencyPaymentBulkReferences" ] }, { "ref": "ApplicationErrorCodes.PAYMENT_BENEFICIARY_NOT_ACTIVE", "code": -18103, "name": "PAYMENT_BENEFICIARY_NOT_ACTIVE", "httpStatus": 409, "message": "The selected payment beneficiary is not active.", "operations": [ "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "PaymentsErrorCode.CONFLICT", "code": "CONFLICT", "name": "CONFLICT", "httpStatus": 409, "message": "Resource conflict.", "operations": [ "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBeneficiaries", "putV2PaymentsBulkWithdrawalsBeneficiariesById" ] }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "code": -15116, "name": "UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Daily deposit reference generation limit exceeded", "operations": [ "postV2WalletFiatByCurrencyPaymentReferences", "postV2WalletFiatByCurrencyPaymentBulkReferences" ] }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "code": -15119, "name": "UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED", "httpStatus": 429, "message": "Total deposit reference limit reached", "operations": [ "postV2WalletFiatByCurrencyPaymentReferences", "postV2WalletFiatByCurrencyPaymentBulkReferences" ] }, { "ref": "ErrorCodes.FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "code": -15111, "name": "FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Deposits in the selected currency are not supported in your region", "operations": [ "getV1WalletFiatByCurrencyDepositReference", "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol" ] }, { "ref": "ErrorCodes.CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "code": -15134, "name": "CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY", "httpStatus": 451, "message": "Auto-buys in the selected currency are not supported in your region", "operations": [ "getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol" ] }, { "ref": "ErrorCodes.FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "code": -15320, "name": "FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY", "httpStatus": 451, "message": "Withdrawals in the selected currency are not supported in your region", "operations": [ "getV1WalletFiatByCurrencyAccounts", "postV1WalletFiatByCurrencyAccounts", "getV1WalletFiatByCurrencyAccountsById", "getV1WalletFiatByCurrencyBanks", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.API_KEY_REQUEST_BLACKLISTED", "code": -11257, "name": "API_KEY_REQUEST_BLACKLISTED", "httpStatus": 500, "message": "Duplicate message received", "operations": [], "allOperations": true }, { "ref": "ErrorCodes.ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "code": -13423, "name": "ADDRESS_BOOK_ENTRY_CURRENCY_WRONG", "httpStatus": 500, "message": "Address book entry not valid for specified currency", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.BANK_REMOTE_FETCH_FAILURE", "code": -15317, "name": "BANK_REMOTE_FETCH_FAILURE", "httpStatus": 500, "message": "Unable to fetch remote list of banks", "operations": [ "postV1WalletFiatByCurrencyAccounts", "getV1WalletFiatByCurrencyBanks", "postV2FiatPayments" ] }, { "ref": "ErrorCodes.INSUFFICIENT_LIQUIDITY_FOR_BORROW", "code": -19202, "name": "INSUFFICIENT_LIQUIDITY_FOR_BORROW", "httpStatus": 500, "message": "The borrow amount is unavailable currently, please try again later", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ApplicationErrorCodes.CURRENCY_UNDER_MAINTENANCE", "code": -19502, "name": "CURRENCY_UNDER_MAINTENANCE", "httpStatus": 500, "message": "Currency currently under maintenance. Please try again in a few minutes.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments", "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.BLOCKCHAIN_SEND_FAILURE", "code": -29, "name": "BLOCKCHAIN_SEND_FAILURE", "httpStatus": 500, "message": "Unknown Blockchain Send Failure", "operations": [ "postV1WalletCryptoByCurrencyWithdraw" ] }, { "ref": "ErrorCodes.COULD_NOT_GET_RECEIVE_ADDRESS", "code": -30, "name": "COULD_NOT_GET_RECEIVE_ADDRESS", "httpStatus": 500, "message": "Could not get deposit address", "operations": [ "getV1WalletCryptoByCurrencyDepositAddress" ] }, { "ref": "ErrorCodes.WITHDRAW_UNAVAILABLE", "code": -46, "name": "WITHDRAW_UNAVAILABLE", "httpStatus": 500, "message": "Withdrawal currently unavailable.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV2CryptoPayments" ] }, { "ref": "PaymentsErrorCode.INTERNAL_ERROR", "code": "INTERNAL_ERROR", "name": "INTERNAL_ERROR", "httpStatus": 500, "message": "An internal error occurred.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "ApplicationErrorCodes.EXCHANGE_API_ERROR", "code": -16097, "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "PaymentsErrorCode.EXCHANGE_API_ERROR", "code": "EXCHANGE_API_ERROR", "name": "EXCHANGE_API_ERROR", "httpStatus": 502, "message": "Upstream service error.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] }, { "ref": "ApplicationErrorCodes.INTERNAL_TRANSFERS_NOT_AVAILABLE", "code": -11652, "name": "INTERNAL_TRANSFERS_NOT_AVAILABLE", "httpStatus": 503, "message": "Internal transfers are currently not available.", "operations": [ "postV1AccountSubaccountsTransfer" ] }, { "ref": "ErrorCodes.WITHDRAWALS_NOT_AVAILABLE", "code": -12015, "name": "WITHDRAWALS_NOT_AVAILABLE", "httpStatus": 503, "message": "Withdrawals are currently not available.", "operations": [ "postV1WalletCryptoByCurrencyWithdraw", "postV1WalletFiatByCurrencyWithdraw", "postV2FiatPayments", "postV2CryptoPayments" ] }, { "ref": "ApplicationErrorCodes.UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "code": -15117, "name": "UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED", "httpStatus": 503, "message": "Unique deposit references are not available at this time", "operations": [ "getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode", "postV2WalletFiatByCurrencyPaymentReferences", "getV2WalletFiatByCurrencyPaymentReferences", "getV2WalletFiatByCurrencyPaymentDeposits" ] }, { "ref": "ApplicationErrorCodes.BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "code": -15120, "name": "BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED", "httpStatus": 503, "message": "Bulk deposit references are not available at this time", "operations": [ "postV2WalletFiatByCurrencyPaymentBulkReferences", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId", "getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems" ] }, { "ref": "ApplicationErrorCodes.PAYMENTS_BACKEND_PROXY_DISABLED", "code": -16099, "name": "PAYMENTS_BACKEND_PROXY_DISABLED", "httpStatus": 503, "message": "Payments backend is not available.", "operations": [ "getV2PaymentsBulkWithdrawalsBatchesById", "getV2Payments", "getV2PaymentsById", "getV2PaymentsCollectEvents", "getV2PaymentsCollectEventsById", "getV2PaymentsCollectHistory", "getV2PaymentsCollectRunsById", "getV2PaymentsCollectRunsByIdPayments", "getV2PaymentsCollectRunsHistory", "getV2PaymentsCollectSchedules", "getV2PaymentsCollectSettlements", "getV2PaymentsCollectSettlementsById", "getV2PaymentsCollectSettlementsByIdPayments", "getV2PaymentsCollectSettlementsWallet", "getV2PaymentsCollectUpcoming", "getV2PaymentsCollectionsHistory", "getV2PaymentsAccountBalancesByType", "getV2PaymentsBulkWithdrawalsBanks", "getV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatches", "postV2PaymentsBulkWithdrawalsBatchesByIdCancel", "getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote", "putV2PaymentsBulkWithdrawalsBatchesByIdLabel", "getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals", "getV2PaymentsBulkWithdrawalsBeneficiaries", "postV2PaymentsBulkWithdrawalsBeneficiaries", "deleteV2PaymentsBulkWithdrawalsBeneficiariesById", "getV2PaymentsBulkWithdrawalsBeneficiariesById", "putV2PaymentsBulkWithdrawalsBeneficiariesById", "postV2PaymentsBulkWithdrawalsBeneficiariesBulk", "postV2PaymentsBulkWithdrawalsFeeQuote", "getV2PaymentsBulkWithdrawalsWithdrawals", "getV2PaymentsPayoutHistory", "getV2PaymentsPayoutHistoryById" ] } ] }, "x-valr-bundles": [ { "name": "PAYMENTS_READ", "description": "Payments — read collections, disbursements and payments balances, including reads added later", "permissions": [ "COLLECTIONS_READ", "DISBURSEMENTS_READ", "PAYMENTS_BALANCES_READ" ] }, { "name": "COLLECTIONS_WRITE", "description": "Collections — create, update and delete deposit references, and read collections", "permissions": [ "COLLECTIONS_CREATE", "COLLECTIONS_READ", "COLLECTIONS_UPDATE", "COLLECTIONS_DELETE", "PAYMENTS_BALANCES_READ" ] }, { "name": "DISBURSEMENTS_WRITE", "description": "Disbursements — manage beneficiaries and batches, and create batches, which execute immediately", "permissions": [ "DISBURSEMENTS_CREATE", "DISBURSEMENTS_READ", "DISBURSEMENTS_UPDATE", "DISBURSEMENTS_DELETE", "DISBURSEMENTS_APPROVE", "PAYMENTS_BALANCES_READ" ] }, { "name": "TRADING_READ", "description": "Trading — read orders, balances and history", "permissions": [ "TRADING_READ", "ACCOUNT_BALANCES_READ", "TRANSACTION_HISTORY_READ" ] }, { "name": "TRADING_WRITE", "description": "Trading — place, modify and cancel orders, convert, and read orders, balances and history", "permissions": [ "TRADING_READ", "TRADING_CREATE", "CONVERT_CREATE", "ACCOUNT_BALANCES_READ", "TRANSACTION_HISTORY_READ" ] }, { "name": "TREASURY_READ", "description": "Treasury — read balances, history, deposit details, sub-accounts, withdrawals and VALR Pay payments", "permissions": [ "ACCOUNT_BALANCES_READ", "TRANSACTION_HISTORY_READ", "DEPOSITS_READ", "SUB_ACCOUNTS_READ", "WITHDRAWALS_READ", "PAY_READ" ] }, { "name": "TREASURY_WRITE", "description": "Treasury — everything in treasury read, plus manage sub-accounts and move funds between them", "permissions": [ "ACCOUNT_BALANCES_READ", "TRANSACTION_HISTORY_READ", "DEPOSITS_READ", "SUB_ACCOUNTS_READ", "WITHDRAWALS_READ", "PAY_READ", "SUB_ACCOUNTS_MANAGE", "TRANSFERS_CREATE" ] }, { "name": "WITHDRAWALS_WRITE", "description": "Withdrawals — send crypto and fiat, and read withdrawals and balances", "permissions": [ "WITHDRAWALS_READ", "WITHDRAWALS_CREATE", "ACCOUNT_BALANCES_READ" ] }, { "name": "BANK_ACCOUNTS_WRITE", "description": "Bank accounts — link and remove bank accounts, and onboard and read virtual accounts", "permissions": [ "BANK_ACCOUNTS_MANAGE", "WITHDRAWALS_READ" ] }, { "name": "WEBHOOKS_WRITE", "description": "Webhooks — manage webhook subscriptions", "permissions": [ "WEBHOOKS_READ", "WEBHOOKS_MANAGE" ] }, { "name": "VALR_PAY_WRITE", "description": "VALR Pay — send and reverse payments, and read payment history and balances", "permissions": [ "PAY_READ", "PAY_SEND", "ACCOUNT_BALANCES_READ" ] } ] }