API Reference

KYC

Receivers, their review and terms of service, and KYC documents.

GET
/v1/kyc/receivers

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

take?number

Page size: how many items to return (1 to 100).

Range1 <= value <= 100
Default100
skip?number

How many items to skip before this page (offset).

Range0 <= value
Default0

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers'
Example Response
{  "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}
POST
/v1/kyc/receivers

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. 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*string

individual for a person (KYC) or business for a company (KYB).

Value in"individual""business"
kyc_type*string

Depth of compliance verification: light, standard or enhanced.

Value in"light""standard""enhanced"
email*string

Receiver's email address, at most 160 characters.

country*string

ISO 3166-1 alpha-2 country code, upper case

Match^[A-Z]{2}$
first_name?string

First name of an individual receiver; with last_name it forms the receiver name.

last_name?string

Last name of an individual receiver.

date_of_birth?string

ISO 8601 date-time with an offset (the fiat partner rejects date-only values).

Formatdate-time
tax_id?string

Receiver's tax id.

occupation?string

Occupation of an individual receiver.

id_doc_country?string

ISO 3166-1 alpha-2 country code, upper case

Match^[A-Z]{2}$
id_doc_type?string

Type of the identity document (for example PASSPORT).

id_doc_front_file?string

file_url from POST /v1/kyc/upload

id_doc_back_file?string

Back of the identity document: a file_url from POST /v1/kyc/upload.

selfie_file?string

Selfie of the person: a file_url from POST /v1/kyc/upload.

account_purpose?string

Purpose of the account, as a fiat partner code (for example receiving_payments).

account_purpose_other?string

Free-text account purpose, forwarded to the fiat partner with account_purpose.

source_of_funds_doc_type?string

Type of the source-of-funds document, as a fiat partner code (for example employment).

source_of_funds_doc_file?string

Source-of-funds document: a file_url from POST /v1/kyc/upload.

source_of_wealth?string

Source of the receiver's wealth, forwarded to the fiat partner.

sole_proprietor_doc_type?string

master_service_agreement | salary_slip | bank_statement

proof_of_address_doc_type?string

Type of the proof-of-address document (for example UTILITY_BILL).

proof_of_address_doc_file?string

Proof-of-address document: a file_url from POST /v1/kyc/upload.

recipient_relationship?string

Relationship to the recipient, as a fiat partner code (for example self).

purpose_of_transactions?string

Purpose of the receiver's transactions, as a fiat partner code (for example business_transactions); an enhanced KYC field.

purpose_of_transactions_explanation?string

Free-text explanation of purpose_of_transactions; an enhanced KYC field.

legal_name?string

Legal name of a business receiver; it becomes the receiver's name.

alternate_name?string

Alternate name of a business receiver.

business_type?string

Type of business, as a fiat partner code (for example cooperative).

business_industry?string

Industry code of a business receiver, such as the NAICS code 541511.

business_description?string

What a business receiver does.

formation_date?string

ISO 8601 date-time with an offset (the fiat partner rejects date-only values).

Formatdate-time
estimated_annual_revenue?string

Estimated annual revenue band of a business receiver, as a fiat partner code (for example 1000000_4999999).

publicly_traded?boolean

Whether a business receiver is publicly traded.

website?string

Absolute http(s) URL, without credentials.

Lengthlength <= 2048
incorporation_doc_file?string

Incorporation document of a business receiver: a file_url from POST /v1/kyc/upload.

proof_of_ownership_doc_file?string

Proof-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?string

First line of the receiver's address.

address_line_2?string

Second line of the receiver's address.

city?string

City of the receiver's address.

state_province_region?string

State, province or region of the receiver's address.

postal_code?string

Postal code of the receiver's address.

phone_number?string

Receiver's phone number with its country code.

ip_address?string

Receiver's IP address, forwarded to the fiat partner.

external_id?string

Your own id for this receiver

image_url?string

URL 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?string

Accepted 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.

Example Request
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"}'
Example Response
{  "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"}
GET
/v1/kyc/receivers/{id}

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string

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.

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string'
Example Response
{  "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"}
PATCH
/v1/kyc/receivers/{id}

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. 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?string

individual for a person (KYC) or business for a company (KYB).

Value in"individual""business"
kyc_type?string

Depth of compliance verification: light, standard or enhanced.

Value in"light""standard""enhanced"
email?string

Receiver's email address, at most 160 characters.

country?string

ISO 3166-1 alpha-2 country code, upper case

Match^[A-Z]{2}$
first_name?string

First name of an individual receiver; with last_name it forms the receiver name.

last_name?string

Last name of an individual receiver.

date_of_birth?string

ISO 8601 date-time with an offset (the fiat partner rejects date-only values).

Formatdate-time
tax_id?string

Receiver's tax id.

occupation?string

Occupation of an individual receiver.

id_doc_country?string

ISO 3166-1 alpha-2 country code, upper case

Match^[A-Z]{2}$
id_doc_type?string

Type of the identity document (for example PASSPORT).

id_doc_front_file?string

file_url from POST /v1/kyc/upload

id_doc_back_file?string

Back of the identity document: a file_url from POST /v1/kyc/upload.

selfie_file?string

Selfie of the person: a file_url from POST /v1/kyc/upload.

account_purpose?string

Purpose of the account, as a fiat partner code (for example receiving_payments).

account_purpose_other?string

Free-text account purpose, forwarded to the fiat partner with account_purpose.

source_of_funds_doc_type?string

Type of the source-of-funds document, as a fiat partner code (for example employment).

source_of_funds_doc_file?string

Source-of-funds document: a file_url from POST /v1/kyc/upload.

source_of_wealth?string

Source of the receiver's wealth, forwarded to the fiat partner.

sole_proprietor_doc_type?string

master_service_agreement | salary_slip | bank_statement

proof_of_address_doc_type?string

Type of the proof-of-address document (for example UTILITY_BILL).

proof_of_address_doc_file?string

Proof-of-address document: a file_url from POST /v1/kyc/upload.

recipient_relationship?string

Relationship to the recipient, as a fiat partner code (for example self).

purpose_of_transactions?string

Purpose of the receiver's transactions, as a fiat partner code (for example business_transactions); an enhanced KYC field.

purpose_of_transactions_explanation?string

Free-text explanation of purpose_of_transactions; an enhanced KYC field.

legal_name?string

Legal name of a business receiver; it becomes the receiver's name.

alternate_name?string

Alternate name of a business receiver.

business_type?string

Type of business, as a fiat partner code (for example cooperative).

business_industry?string

Industry code of a business receiver, such as the NAICS code 541511.

business_description?string

What a business receiver does.

formation_date?string

ISO 8601 date-time with an offset (the fiat partner rejects date-only values).

Formatdate-time
estimated_annual_revenue?string

Estimated annual revenue band of a business receiver, as a fiat partner code (for example 1000000_4999999).

publicly_traded?boolean

Whether a business receiver is publicly traded.

website?string

Absolute http(s) URL, without credentials.

Lengthlength <= 2048
incorporation_doc_file?string

Incorporation document of a business receiver: a file_url from POST /v1/kyc/upload.

proof_of_ownership_doc_file?string

Proof-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?string

First line of the receiver's address.

address_line_2?string

Second line of the receiver's address.

city?string

City of the receiver's address.

state_province_region?string

State, province or region of the receiver's address.

postal_code?string

Postal code of the receiver's address.

phone_number?string

Receiver's phone number with its country code.

ip_address?string

Receiver's IP address, forwarded to the fiat partner.

external_id?string

Your own id for this receiver

image_url?string

URL 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?string

Accepted 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.

Example Request
curl -X PATCH 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "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"}
DELETE
/v1/kyc/receivers/{id}

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string

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.

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.

Example Request
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string'
Example Response
{  "id": "clz9xreceiver01",  "deleted": true}
POST
/v1/kyc/receivers/{id}/approve

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. body

Approval of a pending_review receiver: requests its terms-of-service link and moves it to pending_user.

redirect_url*string

Where the fiat partner redirects the customer after they accept the terms. Must be https and on the consumer allow-list.

expected_version?number

The 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.

Example Request
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"}'
Example Response
{  "url": "https://partner.example/terms-of-service?session_token=tos_example",  "email": "customer@example.com"}
POST
/v1/kyc/receivers/{id}/tos

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. 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.

Default"code"
Value in"code""email"
redirect_url*string

Where 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.

Example Request
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"}'
Example Response
{  "url": "https://partner.example/terms-of-service?session_token=tos_example",  "email": "customer@example.com",  "channel": "code"}
POST
/v1/kyc/receivers/{id}/enable

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. body

The accepted terms-of-service id that creates an approved (pending_user) receiver at the fiat partner.

tos_id*string

Accepted 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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/enable' \  -H 'Content-Type: application/json' \  -d '{  "tos_id": "to_a1b2c3d4e5f6g7h"}'
Example Response
{  "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"}
PATCH
/v1/kyc/receivers/{id}/access

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. body

The receiver's fiat-access kill-switch for onramp and offramp, independent of its KYC status.

disabled*boolean

true = 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.

Example Request
curl -X PATCH 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/access' \  -H 'Content-Type: application/json' \  -d '{  "disabled": true}'
Example Response
{  "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"}
POST
/v1/kyc/upload

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

multipart/form-data
  1. body
file*unknown
bucket?string
Value in"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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/upload' \  -F 'file=null'
Example Response
{  "file_url": "https://files.partner.example/uploads/onboarding/doc_example.pdf"}
POST
/v1/kyc/terms-of-service

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

Starts the fiat partner's hosted terms-of-service acceptance; the customer returns to redirect_url with a tos_id.

redirect_url*string

Where the fiat partner redirects after acceptance (gets ?tos_id=...). Must be https and on the consumer allow-list.

receiver_id?string

Existing receiver to (re)accept updated terms for.

idempotency_key?string

UUID 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.

Example Request
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"}'
Example Response
{  "url": "https://partner.example/terms-of-service?session_token=tos_example"}