KYC
Receivers, their review and terms of service, and KYC documents.
Reads the local mirror only, newest first, on the fiat partner instance of the key's network. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }, where total counts every matching receiver. The stored KYC dossier (tax id, documents, owners) is never returned.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
take?numberPage size: how many items to return (1 to 100).
1 <= value <= 100100skip?numberHow many items to skip before this page (offset).
0 <= value0OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers'{ "data": [ { "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z" } ], "total": 1, "take": 100, "skip": 0}Stores the receiver here and sends nothing to the fiat partner yet: it is created there only by POST /v1/kyc/receivers/{id}/enable, after the review and the customer's acceptance of the terms. A body with KYC data (tax id, date of birth, documents, legal name, formation date or owners) starts in pending_review, a bare registration in inactive. The receiver belongs to the fiat partner instance of the key's network (production for a mainnet key, development otherwise), and the stored dossier is never returned.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
A receiver, the person (KYC) or business (KYB) behind onramp and offramp: stored here and created at the fiat partner only on enable. With KYC data (tax_id, date_of_birth, id_doc_front_file, selfie_file, legal_name, formation_date or owners) it starts in pending_review, otherwise in inactive.
type*stringindividual for a person (KYC) or business for a company (KYB).
"individual""business"kyc_type*stringDepth of compliance verification: light, standard or enhanced.
"light""standard""enhanced"email*stringReceiver's email address, at most 160 characters.
country*stringISO 3166-1 alpha-2 country code, upper case
^[A-Z]{2}$first_name?stringFirst name of an individual receiver; with last_name it forms the receiver name.
last_name?stringLast name of an individual receiver.
date_of_birth?stringISO 8601 date-time with an offset (the fiat partner rejects date-only values).
date-timetax_id?stringReceiver's tax id.
occupation?stringOccupation of an individual receiver.
id_doc_country?stringISO 3166-1 alpha-2 country code, upper case
^[A-Z]{2}$id_doc_type?stringType of the identity document (for example PASSPORT).
id_doc_front_file?stringfile_url from POST /v1/kyc/upload
id_doc_back_file?stringBack of the identity document: a file_url from POST /v1/kyc/upload.
selfie_file?stringSelfie of the person: a file_url from POST /v1/kyc/upload.
account_purpose?stringPurpose of the account, as a fiat partner code (for example receiving_payments).
account_purpose_other?stringFree-text account purpose, forwarded to the fiat partner with account_purpose.
source_of_funds_doc_type?stringType of the source-of-funds document, as a fiat partner code (for example employment).
source_of_funds_doc_file?stringSource-of-funds document: a file_url from POST /v1/kyc/upload.
source_of_wealth?stringSource of the receiver's wealth, forwarded to the fiat partner.
sole_proprietor_doc_type?stringmaster_service_agreement | salary_slip | bank_statement
proof_of_address_doc_type?stringType of the proof-of-address document (for example UTILITY_BILL).
proof_of_address_doc_file?stringProof-of-address document: a file_url from POST /v1/kyc/upload.
recipient_relationship?stringRelationship to the recipient, as a fiat partner code (for example self).
purpose_of_transactions?stringPurpose of the receiver's transactions, as a fiat partner code (for example business_transactions); an enhanced KYC field.
purpose_of_transactions_explanation?stringFree-text explanation of purpose_of_transactions; an enhanced KYC field.
legal_name?stringLegal name of a business receiver; it becomes the receiver's name.
alternate_name?stringAlternate name of a business receiver.
business_type?stringType of business, as a fiat partner code (for example cooperative).
business_industry?stringIndustry code of a business receiver, such as the NAICS code 541511.
business_description?stringWhat a business receiver does.
formation_date?stringISO 8601 date-time with an offset (the fiat partner rejects date-only values).
date-timeestimated_annual_revenue?stringEstimated annual revenue band of a business receiver, as a fiat partner code (for example 1000000_4999999).
publicly_traded?booleanWhether a business receiver is publicly traded.
website?stringAbsolute http(s) URL, without credentials.
length <= 2048incorporation_doc_file?stringIncorporation document of a business receiver: a file_url from POST /v1/kyc/upload.
proof_of_ownership_doc_file?stringProof-of-ownership document of a business receiver: a file_url from POST /v1/kyc/upload.
owners?array<>Beneficial owners and controlling persons of a business receiver.
address_line_1?stringFirst line of the receiver's address.
address_line_2?stringSecond line of the receiver's address.
city?stringCity of the receiver's address.
state_province_region?stringState, province or region of the receiver's address.
postal_code?stringPostal code of the receiver's address.
phone_number?stringReceiver's phone number with its country code.
ip_address?stringReceiver's IP address, forwarded to the fiat partner.
external_id?stringYour own id for this receiver
image_url?stringURL of a display image for the receiver. With external_id, the only field a non-admin key may change once the receiver exists at the fiat partner.
tos_id?stringAccepted terms-of-service id (from the redirect of POST /v1/kyc/terms-of-service). Required by the fiat partner to create a receiver.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers' \ -H 'Content-Type: application/json' \ -d '{ "type": "individual", "kyc_type": "standard", "email": "jane@acme.com", "country": "US"}'{ "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z"}For a receiver that already exists at the fiat partner, reads it there and updates the local mirror first, so kycStatus is the fiat partner's current one; when the fiat partner cannot be reached, the stored row is answered instead of an error. A receiver not yet at the fiat partner (inactive, pending_review, pending_user) is answered from the local row.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringOK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string'{ "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z"}Before the receiver exists at the fiat partner, the patch is merged into the stored registration, any change bumps dossierVersion, and editing a pending_user receiver (or adding KYC data to an inactive one) moves it to pending_review. After that the patch is sent to the fiat partner, and a key without the admin role may change only external_id and image_url. tos_id is always ignored: the accepted terms cannot be changed.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
Changes to a receiver: any field of the create body, all optional. tos_id is ignored, and once the receiver exists at the fiat partner a non-admin key may change only external_id and image_url.
type?stringindividual for a person (KYC) or business for a company (KYB).
"individual""business"kyc_type?stringDepth of compliance verification: light, standard or enhanced.
"light""standard""enhanced"email?stringReceiver's email address, at most 160 characters.
country?stringISO 3166-1 alpha-2 country code, upper case
^[A-Z]{2}$first_name?stringFirst name of an individual receiver; with last_name it forms the receiver name.
last_name?stringLast name of an individual receiver.
date_of_birth?stringISO 8601 date-time with an offset (the fiat partner rejects date-only values).
date-timetax_id?stringReceiver's tax id.
occupation?stringOccupation of an individual receiver.
id_doc_country?stringISO 3166-1 alpha-2 country code, upper case
^[A-Z]{2}$id_doc_type?stringType of the identity document (for example PASSPORT).
id_doc_front_file?stringfile_url from POST /v1/kyc/upload
id_doc_back_file?stringBack of the identity document: a file_url from POST /v1/kyc/upload.
selfie_file?stringSelfie of the person: a file_url from POST /v1/kyc/upload.
account_purpose?stringPurpose of the account, as a fiat partner code (for example receiving_payments).
account_purpose_other?stringFree-text account purpose, forwarded to the fiat partner with account_purpose.
source_of_funds_doc_type?stringType of the source-of-funds document, as a fiat partner code (for example employment).
source_of_funds_doc_file?stringSource-of-funds document: a file_url from POST /v1/kyc/upload.
source_of_wealth?stringSource of the receiver's wealth, forwarded to the fiat partner.
sole_proprietor_doc_type?stringmaster_service_agreement | salary_slip | bank_statement
proof_of_address_doc_type?stringType of the proof-of-address document (for example UTILITY_BILL).
proof_of_address_doc_file?stringProof-of-address document: a file_url from POST /v1/kyc/upload.
recipient_relationship?stringRelationship to the recipient, as a fiat partner code (for example self).
purpose_of_transactions?stringPurpose of the receiver's transactions, as a fiat partner code (for example business_transactions); an enhanced KYC field.
purpose_of_transactions_explanation?stringFree-text explanation of purpose_of_transactions; an enhanced KYC field.
legal_name?stringLegal name of a business receiver; it becomes the receiver's name.
alternate_name?stringAlternate name of a business receiver.
business_type?stringType of business, as a fiat partner code (for example cooperative).
business_industry?stringIndustry code of a business receiver, such as the NAICS code 541511.
business_description?stringWhat a business receiver does.
formation_date?stringISO 8601 date-time with an offset (the fiat partner rejects date-only values).
date-timeestimated_annual_revenue?stringEstimated annual revenue band of a business receiver, as a fiat partner code (for example 1000000_4999999).
publicly_traded?booleanWhether a business receiver is publicly traded.
website?stringAbsolute http(s) URL, without credentials.
length <= 2048incorporation_doc_file?stringIncorporation document of a business receiver: a file_url from POST /v1/kyc/upload.
proof_of_ownership_doc_file?stringProof-of-ownership document of a business receiver: a file_url from POST /v1/kyc/upload.
owners?array<>Beneficial owners and controlling persons of a business receiver.
address_line_1?stringFirst line of the receiver's address.
address_line_2?stringSecond line of the receiver's address.
city?stringCity of the receiver's address.
state_province_region?stringState, province or region of the receiver's address.
postal_code?stringPostal code of the receiver's address.
phone_number?stringReceiver's phone number with its country code.
ip_address?stringReceiver's IP address, forwarded to the fiat partner.
external_id?stringYour own id for this receiver
image_url?stringURL of a display image for the receiver. With external_id, the only field a non-admin key may change once the receiver exists at the fiat partner.
tos_id?stringAccepted terms-of-service id (from the redirect of POST /v1/kyc/terms-of-service). Required by the fiat partner to create a receiver.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
kyc_review_required: the receiver already exists at the fiat partner and the patch touches a field other than external_id or image_url. Only an elevated key (admin role) may rewrite identity at the provider; before enabling, the same edit sends the receiver back to review instead.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X PATCH 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z"}Deletes the receiver at the fiat partner when it was ever created there, then the local row, and records the deletion in the audit log. A receiver that never reached the fiat partner is deleted locally only.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringOK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string'{ "id": "clz9xreceiver01", "deleted": true}The review gate before anything reaches the fiat partner: only a key with the admin role may approve (any other key gets 403 kyc_review_required), and only a pending_review receiver. It requests the fiat partner's hosted terms-of-service link for redirect_url (https, on this consumer's allow-list), moves the receiver to pending_user and returns the link with the receiver's email; nothing is emailed, the caller delivers it. Send expected_version (the dossierVersion you reviewed) so an edit made since is a 409 kyc_state_invalid instead of an approval of unreviewed data.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
Approval of a pending_review receiver: requests its terms-of-service link and moves it to pending_user.
redirect_url*stringWhere the fiat partner redirects the customer after they accept the terms. Must be https and on the consumer allow-list.
expected_version?numberThe receiver's dossierVersion as you read it. A 409 kyc_state_invalid if the KYC data changed since: re-read, review again, approve that version. Omitted approves whatever is stored now.
Receiver approved; terms link returned
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
kyc_review_required: the API key is not elevated (admin role). A key may submit KYC data or approve it, not both.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
kyc_state_invalid: the receiver is not in 'pending_review', or the KYC data changed after you read it (expected_version names a version that is no longer current). Re-read the receiver, review it again, and approve that version.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/approve' \ -H 'Content-Type: application/json' \ -d '{ "redirect_url": "https://dev.cosmospay.lat/kyc/return/org/dev/clz9xreceiver01"}'{ "url": "https://partner.example/terms-of-service?session_token=tos_example", "email": "customer@example.com"}Only for a pending_user receiver (approved, terms not yet accepted); any other status is 400 kyc_state_invalid. Requests a fresh hosted link from the fiat partner for redirect_url (https, on this consumer's allow-list) and returns it with the receiver's email. channel: email sends nothing itself: it records the send, allowed once per 24 hours per receiver (400 validation_failed inside that window, 409 kyc_state_invalid when two race), and the caller emails the returned link; channel: code (the default) has no such limit.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
A request for a fresh terms-of-service link for a pending_user receiver.
channel?string'code' returns the hosted ToS URL to display. 'email' records an email send, allowed once per 24 hours per receiver; it sends nothing itself, so you email the returned link.
"code""code""email"redirect_url*stringWhere the fiat partner redirects after acceptance (gets ?tos_id=...). Must be https and on the consumer allow-list.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/tos' \ -H 'Content-Type: application/json' \ -d '{ "redirect_url": "https://yourapp.com/kyc/return"}'{ "url": "https://partner.example/terms-of-service?session_token=tos_example", "email": "customer@example.com", "channel": "code"}Creates the receiver at the fiat partner: replays the stored registration with the tos_id the customer got by accepting the terms, then replaces the local placeholder id with the fiat partner's and mirrors the fiat partner's KYC status. Only a pending_user receiver whose current dossierVersion is the approved one; otherwise, or when another enable is running, 409 kyc_state_invalid. A receiver already at the fiat partner is not created again: it is refreshed from the fiat partner and returned.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
The accepted terms-of-service id that creates an approved (pending_user) receiver at the fiat partner.
tos_id*stringAccepted terms-of-service id (the ?tos_id=... from the ToS redirect).
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
kyc_state_invalid: an invalid KYC status transition (e.g. the receiver is not in 'pending_user').
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/enable' \ -H 'Content-Type: application/json' \ -d '{ "tos_id": "to_a1b2c3d4e5f6g7h"}'{ "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z"}Sets disabled on the receiver. While disabled, onramp, offramp and adding wallets, bank accounts or virtual accounts for it are refused with 403 account_disabled, whatever its KYC status. Only a key with the admin role may call it (any other key gets 403 insufficient_scope), so a tenant cannot lift a switch an operator set. Local only: nothing is sent to the fiat partner.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
The receiver's fiat-access kill-switch for onramp and offramp, independent of its KYC status.
disabled*booleantrue = disable the fiat account, false = enable.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
The API key is not elevated (admin role); a tenant key cannot lift a kill-switch an operator applied.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X PATCH 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/access' \ -H 'Content-Type: application/json' \ -d '{ "disabled": true}'{ "id": "clz9xreceiver01", "blindpayId": "re_000000000000", "type": "individual", "kycType": "standard", "kycStatus": "verifying", "email": "jane@acme.com", "name": "Jane Doe", "country": "US", "externalId": "cust_001", "disabled": false, "dossierVersion": 3, "reviewedVersion": 3, "createdAt": "2026-06-28T12:00:00.000Z", "updatedAt": "2026-06-28T12:00:00.000Z"}Multipart: one file part (JPEG, PNG, WebP, HEIC/HEIF or PDF, up to 10 MB, its bytes checked against the declared type) and an optional bucket (onboarding by default, avatar or limit_increase). the fiat partner stores the file on the instance of the key's network and nothing is kept here; pass the returned file_url in the receiver's *_file fields. the fiat partner keeps a stored file even when a later step fails, which is why the route is budgeted per address and per consumer.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
multipart/form-data- body
file*unknownbucket?string"avatar""onboarding""limit_increase"Created
The multipart form was refused (validation_failed), before the provider saw anything: more than 4 text fields; a text field longer than 1024 bytes; more than 1 file; a declared content type other than image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf; file bytes that do not match the declared content type; a missing file part; or an unknown bucket.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
The file is larger than 10485760 bytes (payload_too_large). Multer stops reading at the limit, so nothing reaches the provider.
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/upload' \ -F 'file=null'{ "file_url": "https://files.partner.example/uploads/onboarding/doc_example.pdf"}Asks the fiat partner for a hosted terms-of-service page and returns its URL; after acceptance the fiat partner redirects to redirect_url (https, on this consumer's allow-list) with a tos_id query parameter. With receiver_id (the fiat partner id of a receiver this consumer owns, otherwise 404) the terms are for that existing receiver. idempotency_key is forwarded to the fiat partner and generated when omitted; every call creates a record there, hence the budgets.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
Starts the fiat partner's hosted terms-of-service acceptance; the customer returns to redirect_url with a tos_id.
redirect_url*stringWhere the fiat partner redirects after acceptance (gets ?tos_id=...). Must be https and on the consumer allow-list.
receiver_id?stringExisting receiver to (re)accept updated terms for.
idempotency_key?stringUUID for idempotency. Auto-generated when omitted.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/terms-of-service' \ -H 'Content-Type: application/json' \ -d '{ "redirect_url": "https://yourapp.com/kyc/return"}'{ "url": "https://partner.example/terms-of-service?session_token=tos_example"}