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.
For the hosted checkout: the amount, the merchant, the release model, the deadlines, the status and buyerActions, what the buyer may do now. The id is the capability: nothing about the merchant’s account or reference is returned. Answered with Cache-Control: no-store and budgeted per client address.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
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 protected payment has this id.
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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10'{ "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" }}The first call deploys the payment’s contract (Cosmos Pay pays for it) and binds buyer, once Horizon shows it holds the amount in USDC; a different buyer afterwards, or one the merchant did not name, is 409. Answers the checked deposit for buyer to sign and send to the link’s submit, before the funding window closes.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
application/json- body
buyer*stringThe buyer’s Stellar account (G...): it signs the deposit and must hold the amount in USDC. The first fund binds it as the buyer.
OK
validation_failed: buyer is the merchant, a platform account or an account that does not exist. invalid_state_transition: the payment is no longer open for funding. trustline_missing: the buyer does not trust USDC, or the merchant cannot receive it. insufficient_balance: the buyer holds less than the amount. provider_error: Trustless Work refused the request.
No protected payment has this id.
protected_payment_buyer_mismatch: another buyer is bound. operation_in_flight: the contract is being deployed by another request; retry.
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/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10/fund' \ -H 'Content-Type: application/json' \ -d '{ "buyer": "GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76"}'{ "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } }}Where the buyer approves (BUYER_RELEASES, BUYER_APPROVES_MERCHANT_RELEASES), for a FUNDED or SHIPPED payment. Answers the checked envelope for the bound buyer to sign and send to the link’s submit.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
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 merchant. provider_error: Trustless Work refused the request.
No protected payment has this id.
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/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10/approve'{ "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } }}Only under BUYER_RELEASES, for an APPROVED payment: the contract pays the merchant the amount less 1.95%. Answers the checked envelope for the bound buyer to sign and send to the link’s submit.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
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 merchant. provider_error: Trustless Work refused the request.
No protected payment has this id.
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/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10/release'{ "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } }}Where the buyer holds a role in the contract, answers built, the dispute for the buyer to sign and submit. Under MERCHANT_RELEASES the buyer holds none, so Cosmos Pay’s platform key opens it (submitted) once signature proves the buyer signed the link’s disputeChallenge before expiresAt.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
application/json- body
reason?stringWhy, kept by Cosmos Pay for the review: Trustless Work V1 takes no reason.
signature?stringOnly when the buyer holds no role in the contract (MERCHANT_RELEASES): the buyer’s signature (base64) over disputeChallenge.message from the link’s read.
expiresAt?stringWith signature: disputeChallenge.expiresAt, exactly as it is in the signed message.
OK
invalid_state_transition: the payment is not funded, or already settled. protected_payment_signature_invalid: the signed message is missing, does not verify against the buyer, or expired. provider_error: Trustless Work refused the request.
No protected payment has this id.
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/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10/dispute' \ -H 'Content-Type: application/json' \ -d '{}'{ "built": { "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } } }, "submitted": { "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } } }}Relays xdr through Trustless Work only when it is a signed copy of a transaction this link built for the bound buyer, before it expires. Relayed once: the answer is stored and a replay returns it; on SUCCESS the payment moves.
id*stringThe protected payment id (a uuid), as in the link https://payments.cosmospay.lat/protected/<id>.
application/json- body
xdr*stringThe transaction a build of this payment link returned, signed unchanged by the buyer (base64 envelope XDR).
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 protected payment has this id.
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.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/protected-payment-links/3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10/submit' \ -H 'Content-Type: application/json' \ -d '{ "xdr": "string"}'{ "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" }, "buyerActions": [ "fund" ], "disputeChallenge": { "message": "Cosmos Pay protected payment dispute\npayment: 3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10\naccount: GARMB7W3FCR3GKIM3FLWVJASC2PUZ4VHUJZTNJVWWKNTCJNKO6TBCT76\nnetwork: testnet\nexpires: 2026-11-02T18:10:00.000Z", "expiresAt": "2026-11-02T18:10:00.000Z" } }}Health
Liveness and readiness probes.
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.