API Reference

Protected payments

Payments held until delivery. Create a protected payment, choose who confirms delivery and what happens at the deadline, then ship, approve, release or dispute it. The buyer pays USDC into a smart contract on Stellar, and the funds are released to your wallet on the terms you chose.

List your protected payments

GET
/v1/protected-payments

Newest first, as { data, total, take, skip } with take up to 100 (default 20). Only payments on the key’s network, narrowed by status when given, as this service last read them from their contracts.

Requires the payments:read scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Query Parameters

status?string

Only protected payments in this status.

Value in"CREATED""AWAITING_FUNDING""FUNDED""SHIPPED""APPROVED""RELEASED""DISPUTED""RESOLVED""EXPIRED""CANCELLED"
take?number

How many to return per page (1 to 100).

Rangevalue <= 100
Default20
skip?number

How many to skip before the page starts (newest first).

Default0

Response Body

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/protected-payments'
Example Response
{  "data": [    {      "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",      "network": "testnet",      "status": "CREATED",      "releaseModel": "BUYER_RELEASES",      "deadlinePolicy": "MANUAL_REVIEW",      "title": "Order #1042",      "description": "string",      "amount": "125.5",      "asset": "USDC",      "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",      "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",      "buyerAddress": "string",      "platformFeeBps": 165,      "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",      "fundingExpiresAt": "2019-08-24T14:15:22Z",      "deliveryWindowHours": 168,      "deliveryDeadlineAt": "2019-08-24T14:15:22Z",      "deadlinePassedAt": "2019-08-24T14:15:22Z",      "evidence": "string",      "fundedAt": "2019-08-24T14:15:22Z",      "shippedAt": "2019-08-24T14:15:22Z",      "approvedAt": "2019-08-24T14:15:22Z",      "releasedAt": "2019-08-24T14:15:22Z",      "disputedAt": "2019-08-24T14:15:22Z",      "resolvedAt": "2019-08-24T14:15:22Z",      "resolution": {        "buyer": "100",        "merchant": "25.5",        "decidedBy": "ops@cosmospay.lat"      },      "cancelledAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "fees": {        "trustlessWorkBps": 30,        "platformBps": 165,        "totalBps": 195,        "merchantReceives": "123.05275"      },      "reference": "string",      "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",      "disputeResolverAddress": "string",      "disputedBy": "BUYER",      "disputeReason": "string",      "lastSyncedAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"    }  ],  "total": 1,  "take": 20,  "skip": 0}

Create a protected payment (the buyer pays into a contract until delivery)

POST
/v1/protected-payments

Creates a protected payment in USDC on the key’s network, with the release model and the deadline policy of your choice, and answers checkoutUrl, the page to send the buyer. Nothing happens on-chain yet: the contract is deployed when the buyer first funds it. Emits PROTECTED_PAYMENT_CREATED; the same Idempotency-Key with the same request returns the stored payment.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Header Parameters

Idempotency-Key?string

Optional idempotency key. A retry with the same key and the same request returns the stored payment unchanged; the same key with a different request is 409 idempotency_conflict. Takes precedence over body.idempotencyKey.

Request Body

application/json
  1. body

A protected payment to create: the buyer pays USDC into a Trustless Work contract and it is released to the merchant on the release model chosen here.

amount*string

The amount in USDC, a decimal with up to 7 places, from 1 to 1000000. The fees (1.95% by default) come out of what the merchant receives.

releaseModel*string

Who approves delivery and who releases the money: BUYER_RELEASES (the buyer approves and releases), MERCHANT_RELEASES (the merchant does both), BUYER_APPROVES_MERCHANT_RELEASES (the buyer approves, the merchant collects).

Value in"BUYER_RELEASES""MERCHANT_RELEASES""BUYER_APPROVES_MERCHANT_RELEASES"
deadlinePolicy*string

What happens when the delivery deadline passes on a funded payment that was not released: MANUAL_REVIEW (Cosmos Pay ops decides), REFUND_BUYER or RELEASE_MERCHANT (decided automatically).

Value in"MANUAL_REVIEW""REFUND_BUYER""RELEASE_MERCHANT"
deliveryWindowHours*number

Hours from funding until the delivery deadline (1 to 2160, 90 days).

Range1 <= value <= 2160
fundingWindowHours?number

Hours the buyer has to fund it (1 to 720); unfunded after that, it expires.

Range1 <= value <= 720
Default72
merchantAddress*string

The Stellar account (G...) that receives the money. It must trust USDC.

buyerAddress?string

The buyer’s Stellar account (G...), when the merchant knows it. Set, only this account may fund the payment; unset, the first account that funds it is bound as the buyer.

title*string

Shown to the buyer and written into the contract.

description?string

Shown to the buyer and written into the contract.

reference?string

The merchant’s own reference. Never shown to the buyer, never on-chain.

idempotencyKey?string

Optional idempotency key. Prefer the Idempotency-Key header; the same key with the same request returns the stored payment, with another request it is 409 idempotency_conflict.

Response Body

Created

validation_failed: the body fails validation, the buyer is the merchant, or a party is one of the platform accounts. invalid_amount: outside 1 to 1000000 USDC.

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.

idempotency_conflict: This Idempotency-Key was already used for a different request

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.

Protected payments are not configured on the key’s network, or the deadline policy needs a resolver this deployment does not have.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/protected-payments' \  -H 'Content-Type: application/json' \  -d '{  "amount": "125.50",  "releaseModel": "BUYER_RELEASES",  "deadlinePolicy": "MANUAL_REVIEW",  "deliveryWindowHours": 168,  "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "title": "Order #1042"}'
Example Response
{  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",  "network": "testnet",  "status": "CREATED",  "releaseModel": "BUYER_RELEASES",  "deadlinePolicy": "MANUAL_REVIEW",  "title": "Order #1042",  "description": "string",  "amount": "125.5",  "asset": "USDC",  "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",  "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "buyerAddress": "string",  "platformFeeBps": 165,  "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",  "fundingExpiresAt": "2019-08-24T14:15:22Z",  "deliveryWindowHours": 168,  "deliveryDeadlineAt": "2019-08-24T14:15:22Z",  "deadlinePassedAt": "2019-08-24T14:15:22Z",  "evidence": "string",  "fundedAt": "2019-08-24T14:15:22Z",  "shippedAt": "2019-08-24T14:15:22Z",  "approvedAt": "2019-08-24T14:15:22Z",  "releasedAt": "2019-08-24T14:15:22Z",  "disputedAt": "2019-08-24T14:15:22Z",  "resolvedAt": "2019-08-24T14:15:22Z",  "resolution": {    "buyer": "100",    "merchant": "25.5",    "decidedBy": "ops@cosmospay.lat"  },  "cancelledAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z",  "fees": {    "trustlessWorkBps": 30,    "platformBps": 165,    "totalBps": 195,    "merchantReceives": "123.05275"  },  "reference": "string",  "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "disputeResolverAddress": "string",  "disputedBy": "BUYER",  "disputeReason": "string",  "lastSyncedAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"}

Get one of your protected payments

GET
/v1/protected-payments/{id}

The payment as this service last read it from its contract (the sync job reads open contracts every 30 seconds), with its fees and checkoutUrl.

Requires the payments:read scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Response Body

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/protected-payments/string'
Example Response
{  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",  "network": "testnet",  "status": "CREATED",  "releaseModel": "BUYER_RELEASES",  "deadlinePolicy": "MANUAL_REVIEW",  "title": "Order #1042",  "description": "string",  "amount": "125.5",  "asset": "USDC",  "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",  "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "buyerAddress": "string",  "platformFeeBps": 165,  "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",  "fundingExpiresAt": "2019-08-24T14:15:22Z",  "deliveryWindowHours": 168,  "deliveryDeadlineAt": "2019-08-24T14:15:22Z",  "deadlinePassedAt": "2019-08-24T14:15:22Z",  "evidence": "string",  "fundedAt": "2019-08-24T14:15:22Z",  "shippedAt": "2019-08-24T14:15:22Z",  "approvedAt": "2019-08-24T14:15:22Z",  "releasedAt": "2019-08-24T14:15:22Z",  "disputedAt": "2019-08-24T14:15:22Z",  "resolvedAt": "2019-08-24T14:15:22Z",  "resolution": {    "buyer": "100",    "merchant": "25.5",    "decidedBy": "ops@cosmospay.lat"  },  "cancelledAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z",  "fees": {    "trustlessWorkBps": 30,    "platformBps": 165,    "totalBps": 195,    "merchantReceives": "123.05275"  },  "reference": "string",  "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "disputeResolverAddress": "string",  "disputedBy": "BUYER",  "disputeReason": "string",  "lastSyncedAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"}

Build the merchant’s "shipped" mark, with tracking evidence

POST
/v1/protected-payments/{id}/ship

For a FUNDED payment: Trustless Work builds the milestone change to shipped with evidence, which this service checks is exactly that call and records for 15 minutes. Sign it with merchantAddress and send it to POST /v1/protected-payments/submit.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Request Body

application/json
  1. body
evidence*string

What the payment shipped with: a tracking number or URL, written into the contract as the milestone’s evidence.

Response Body

OK

invalid_state_transition: the payment is not in a state this action can be built from, or the release model gives it to the other party. provider_error: Trustless Work refused the request.

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.

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/protected-payments/string/ship' \  -H 'Content-Type: application/json' \  -d '{  "evidence": "DHL 1234567890"}'
Example Response
{  "action": "DEPLOY",  "xdr": "AAAAAgAAAAB…",  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a",  "expiresAt": "2019-08-24T14:15:22Z",  "protectedPayment": {    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",    "network": "testnet",    "status": "CREATED",    "releaseModel": "BUYER_RELEASES",    "deadlinePolicy": "MANUAL_REVIEW",    "title": "Order #1042",    "description": "string",    "amount": "125.5",    "asset": "USDC",    "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",    "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "buyerAddress": "string",    "platformFeeBps": 165,    "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",    "fundingExpiresAt": "2019-08-24T14:15:22Z",    "deliveryWindowHours": 168,    "deliveryDeadlineAt": "2019-08-24T14:15:22Z",    "deadlinePassedAt": "2019-08-24T14:15:22Z",    "evidence": "string",    "fundedAt": "2019-08-24T14:15:22Z",    "shippedAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "disputedAt": "2019-08-24T14:15:22Z",    "resolvedAt": "2019-08-24T14:15:22Z",    "resolution": {      "buyer": "100",      "merchant": "25.5",      "decidedBy": "ops@cosmospay.lat"    },    "cancelledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "fees": {      "trustlessWorkBps": 30,      "platformBps": 165,      "totalBps": 195,      "merchantReceives": "123.05275"    },    "reference": "string",    "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "disputeResolverAddress": "string",    "disputedBy": "BUYER",    "disputeReason": "string",    "lastSyncedAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"  }}

Build the merchant’s approval of delivery (MERCHANT_RELEASES)

POST
/v1/protected-payments/{id}/approve

Only where the merchant is the approver (MERCHANT_RELEASES), for a FUNDED or SHIPPED payment. Answers the checked envelope for merchantAddress to sign and submit.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Response Body

OK

invalid_state_transition: the payment is not in a state this action can be built from, or the release model gives it to the other party. provider_error: Trustless Work refused the request.

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.

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/protected-payments/string/approve'
Example Response
{  "action": "DEPLOY",  "xdr": "AAAAAgAAAAB…",  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a",  "expiresAt": "2019-08-24T14:15:22Z",  "protectedPayment": {    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",    "network": "testnet",    "status": "CREATED",    "releaseModel": "BUYER_RELEASES",    "deadlinePolicy": "MANUAL_REVIEW",    "title": "Order #1042",    "description": "string",    "amount": "125.5",    "asset": "USDC",    "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",    "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "buyerAddress": "string",    "platformFeeBps": 165,    "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",    "fundingExpiresAt": "2019-08-24T14:15:22Z",    "deliveryWindowHours": 168,    "deliveryDeadlineAt": "2019-08-24T14:15:22Z",    "deadlinePassedAt": "2019-08-24T14:15:22Z",    "evidence": "string",    "fundedAt": "2019-08-24T14:15:22Z",    "shippedAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "disputedAt": "2019-08-24T14:15:22Z",    "resolvedAt": "2019-08-24T14:15:22Z",    "resolution": {      "buyer": "100",      "merchant": "25.5",      "decidedBy": "ops@cosmospay.lat"    },    "cancelledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "fees": {      "trustlessWorkBps": 30,      "platformBps": 165,      "totalBps": 195,      "merchantReceives": "123.05275"    },    "reference": "string",    "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "disputeResolverAddress": "string",    "disputedBy": "BUYER",    "disputeReason": "string",    "lastSyncedAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"  }}

Build the release of the funds to the merchant

POST
/v1/protected-payments/{id}/release

Where the merchant releases (MERCHANT_RELEASES, BUYER_APPROVES_MERCHANT_RELEASES), for an APPROVED payment. The contract pays the amount less 1.95% to merchantAddress. Answers the checked envelope to sign and submit.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Response Body

OK

invalid_state_transition: the payment is not in a state this action can be built from, or the release model gives it to the other party. provider_error: Trustless Work refused the request.

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.

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/protected-payments/string/release'
Example Response
{  "action": "DEPLOY",  "xdr": "AAAAAgAAAAB…",  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a",  "expiresAt": "2019-08-24T14:15:22Z",  "protectedPayment": {    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",    "network": "testnet",    "status": "CREATED",    "releaseModel": "BUYER_RELEASES",    "deadlinePolicy": "MANUAL_REVIEW",    "title": "Order #1042",    "description": "string",    "amount": "125.5",    "asset": "USDC",    "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",    "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "buyerAddress": "string",    "platformFeeBps": 165,    "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",    "fundingExpiresAt": "2019-08-24T14:15:22Z",    "deliveryWindowHours": 168,    "deliveryDeadlineAt": "2019-08-24T14:15:22Z",    "deadlinePassedAt": "2019-08-24T14:15:22Z",    "evidence": "string",    "fundedAt": "2019-08-24T14:15:22Z",    "shippedAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "disputedAt": "2019-08-24T14:15:22Z",    "resolvedAt": "2019-08-24T14:15:22Z",    "resolution": {      "buyer": "100",      "merchant": "25.5",      "decidedBy": "ops@cosmospay.lat"    },    "cancelledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "fees": {      "trustlessWorkBps": 30,      "platformBps": 165,      "totalBps": 195,      "merchantReceives": "123.05275"    },    "reference": "string",    "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "disputeResolverAddress": "string",    "disputedBy": "BUYER",    "disputeReason": "string",    "lastSyncedAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"  }}

Build the merchant’s dispute

POST
/v1/protected-payments/{id}/dispute

For a FUNDED, SHIPPED or APPROVED payment: answers the dispute for merchantAddress to sign and submit. reason is kept by this service only; Cosmos Pay ops (or the automatic resolver, under an auto deadline policy) then splits the balance between the buyer and the merchant.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Request Body

application/json
  1. body
reason?string

Why, kept by Cosmos Pay for the review: Trustless Work V1 takes no reason.

Response Body

OK

invalid_state_transition: the payment is not in a state this action can be built from, or the release model gives it to the other party. provider_error: Trustless Work refused the request.

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.

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/protected-payments/string/dispute' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "action": "DEPLOY",  "xdr": "AAAAAgAAAAB…",  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a",  "expiresAt": "2019-08-24T14:15:22Z",  "protectedPayment": {    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",    "network": "testnet",    "status": "CREATED",    "releaseModel": "BUYER_RELEASES",    "deadlinePolicy": "MANUAL_REVIEW",    "title": "Order #1042",    "description": "string",    "amount": "125.5",    "asset": "USDC",    "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",    "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "buyerAddress": "string",    "platformFeeBps": 165,    "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",    "fundingExpiresAt": "2019-08-24T14:15:22Z",    "deliveryWindowHours": 168,    "deliveryDeadlineAt": "2019-08-24T14:15:22Z",    "deadlinePassedAt": "2019-08-24T14:15:22Z",    "evidence": "string",    "fundedAt": "2019-08-24T14:15:22Z",    "shippedAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "disputedAt": "2019-08-24T14:15:22Z",    "resolvedAt": "2019-08-24T14:15:22Z",    "resolution": {      "buyer": "100",      "merchant": "25.5",      "decidedBy": "ops@cosmospay.lat"    },    "cancelledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "fees": {      "trustlessWorkBps": 30,      "platformBps": 165,      "totalBps": 195,      "merchantReceives": "123.05275"    },    "reference": "string",    "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "disputeResolverAddress": "string",    "disputedBy": "BUYER",    "disputeReason": "string",    "lastSyncedAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"  }}

Cancel a protected payment nobody funded

POST
/v1/protected-payments/{id}/cancel

Only CREATED, or AWAITING_FUNDING with an empty contract. Refused while a deposit the buyer was handed can still land (it lapses within 15 minutes). Emits PROTECTED_PAYMENT_CANCELLED.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Path Parameters

id*string

Response Body

OK

invalid_state_transition: The resource cannot move to that state from the one it is in

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.

operation_in_flight: A conflicting operation is still settling

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/protected-payments/string/cancel'
Example Response
{  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",  "network": "testnet",  "status": "CREATED",  "releaseModel": "BUYER_RELEASES",  "deadlinePolicy": "MANUAL_REVIEW",  "title": "Order #1042",  "description": "string",  "amount": "125.5",  "asset": "USDC",  "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",  "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "buyerAddress": "string",  "platformFeeBps": 165,  "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",  "fundingExpiresAt": "2019-08-24T14:15:22Z",  "deliveryWindowHours": 168,  "deliveryDeadlineAt": "2019-08-24T14:15:22Z",  "deadlinePassedAt": "2019-08-24T14:15:22Z",  "evidence": "string",  "fundedAt": "2019-08-24T14:15:22Z",  "shippedAt": "2019-08-24T14:15:22Z",  "approvedAt": "2019-08-24T14:15:22Z",  "releasedAt": "2019-08-24T14:15:22Z",  "disputedAt": "2019-08-24T14:15:22Z",  "resolvedAt": "2019-08-24T14:15:22Z",  "resolution": {    "buyer": "100",    "merchant": "25.5",    "decidedBy": "ops@cosmospay.lat"  },  "cancelledAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z",  "fees": {    "trustlessWorkBps": 30,    "platformBps": 165,    "totalBps": 195,    "merchantReceives": "123.05275"  },  "reference": "string",  "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",  "disputeResolverAddress": "string",  "disputedBy": "BUYER",  "disputeReason": "string",  "lastSyncedAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"}

Submit a merchant-signed protected payment transaction

POST
/v1/protected-payments/submit

Relays xdr through Trustless Work only when it is a signed copy of a transaction built for that payment, for merchantAddress, on the key’s network, before it expires. Relayed once: the answer is stored and a replay returns it; on SUCCESS the payment moves and its webhook is emitted.

Requires the payments:write scope.

Authorization

apiKey
headerAuthorizationBearer <API key>

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

Request Body

application/json
  1. body
protectedPaymentId*string

The protected payment the transaction was built for.

Formatuuid
xdr*string

The transaction a build on this service returned, signed unchanged (base64 envelope XDR).

Response Body

OK

validation_failed: xdr is not an envelope, is a fee bump or carries no signature. invalid_state_transition: it expired before it was submitted.

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.

operation_in_flight: A conflicting operation is still settling

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/protected-payments/submit' \  -H 'Content-Type: application/json' \  -d '{  "protectedPaymentId": "b7786366-97b7-4d44-9b69-bb0671e75752",  "xdr": "string"}'
Example Response
{  "action": "DEPLOY",  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a",  "status": "SUCCESS",  "message": "The transaction has been successfully sent to the Stellar network.",  "protectedPayment": {    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",    "network": "testnet",    "status": "CREATED",    "releaseModel": "BUYER_RELEASES",    "deadlinePolicy": "MANUAL_REVIEW",    "title": "Order #1042",    "description": "string",    "amount": "125.5",    "asset": "USDC",    "assetIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",    "merchantAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "buyerAddress": "string",    "platformFeeBps": 165,    "contractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",    "fundingExpiresAt": "2019-08-24T14:15:22Z",    "deliveryWindowHours": 168,    "deliveryDeadlineAt": "2019-08-24T14:15:22Z",    "deadlinePassedAt": "2019-08-24T14:15:22Z",    "evidence": "string",    "fundedAt": "2019-08-24T14:15:22Z",    "shippedAt": "2019-08-24T14:15:22Z",    "approvedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "disputedAt": "2019-08-24T14:15:22Z",    "resolvedAt": "2019-08-24T14:15:22Z",    "resolution": {      "buyer": "100",      "merchant": "25.5",      "decidedBy": "ops@cosmospay.lat"    },    "cancelledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "fees": {      "trustlessWorkBps": 30,      "platformBps": 165,      "totalBps": 195,      "merchantReceives": "123.05275"    },    "reference": "string",    "platformAddress": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76",    "disputeResolverAddress": "string",    "disputedBy": "BUYER",    "disputeReason": "string",    "lastSyncedAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "checkoutUrl": "https://payments.cosmospay.lat/protected/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10"  }}

Protected payment links

The buyer side of a protected payment, called from the hosted checkout without an API key: read the payment, fund it from a Stellar wallet, confirm delivery, release it or open a dispute.