{"openapi":"3.1.0","info":{"title":"GLORESEND API","version":"1.0.0","description":"The GLORESEND API. Sandbox and Live are separate environments with separate base URLs and separate API keys. Sandbox data is simulated and flagged with `test_data: true`. Live money movement is disabled until a payment provider has been authorized for this deployment. Webhooks are signed with the `Gloresend-Signature` header."},"servers":[{"url":"https://api.gloresend.com/sandbox/v1","description":"Sandbox — simulated, no real money"},{"url":"https://api.gloresend.com/v1","description":"Live"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Send your secret API key as a bearer token. Sandbox keys start with `gs_test_`, Live keys with `gs_live_`."}},"schemas":{"Ping":{"type":"object","properties":{"object":{"type":"string","enum":["ping"]},"environment":{"$ref":"#/components/schemas/Environment"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"api_key":{"type":"object","properties":{"id":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["balances:read","transfers:read","transfers:write","cards:read","cards:write","cards:sensitive"]}}},"required":["id","prefix","scopes"]},"server_time":{"type":"string","format":"date-time"}},"required":["object","environment","organization","api_key","server_time"]},"Environment":{"type":"string","enum":["sandbox","live"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"invalid_request"},"code":{"type":"string","example":"validation_error"},"message":{"type":"string","example":"amount: Amounts must be greater than zero."},"param":{"type":"string","example":"amount"},"request_id":{"type":"string","example":"req_8f1c2b7d9a3e4f50"}},"required":["type","code","message"]}},"required":["error"]},"CurrencyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/Currency"},"name":{"type":"string"},"exponent":{"type":"integer"}},"required":["code","name","exponent"]}}},"required":["object","data"]},"Currency":{"type":"string","enum":["USD","EUR","GBP","XOF","XAF","NGN","GHS","KES"],"description":"ISO 4217 currency code."},"BalanceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Balance"}}},"required":["object","data"]},"Balance":{"type":"object","properties":{"object":{"type":"string","enum":["balance"]},"currency":{"$ref":"#/components/schemas/Currency"},"available":{"type":"integer","description":"Funds that can be used for new transfers, in minor units."},"reserved":{"type":"integer","description":"Funds held for transfers that are still processing, in minor units."},"total":{"type":"integer","description":"available + reserved, in minor units."},"test_data":{"type":"boolean","description":"true for every Sandbox object. Sandbox balances are simulated and have no monetary value."}},"required":["object","currency","available","reserved","total","test_data"]},"Transfer":{"type":"object","properties":{"id":{"type":"string","example":"tr_4k2m9q8w7e6r5t3y"},"object":{"type":"string","enum":["transfer"]},"environment":{"$ref":"#/components/schemas/Environment"},"amount":{"type":"integer"},"fee":{"type":"integer","description":"Fee charged by GLORESEND in minor units. Pricing is not yet configured, so this is currently 0."},"currency":{"$ref":"#/components/schemas/Currency"},"status":{"type":"string","enum":["processing","succeeded","failed"]},"destination":{"$ref":"#/components/schemas/MaskedDestination"},"reference":{"type":["string","null"]},"description":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"failure_code":{"type":["string","null"]},"failure_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"test_data":{"type":"boolean"}},"required":["id","object","environment","amount","fee","currency","status","destination","reference","description","metadata","failure_code","failure_message","created_at","completed_at","test_data"]},"MaskedDestination":{"type":"object","properties":{"type":{"type":"string","enum":["bank_account","mobile_money"]},"account_name":{"type":"string"},"country":{"type":"string"},"bank_code":{"type":"string"},"network":{"type":"string"},"last4":{"type":"string","description":"Last four characters of the account or phone number. Full identifiers are never returned or stored after the request."}},"required":["type","account_name","country","last4"]},"CreateTransferRequest":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in the currency's minor unit (for example cents). Integer.","example":125000},"currency":{"$ref":"#/components/schemas/Currency"},"destination":{"$ref":"#/components/schemas/Destination"},"reference":{"type":"string","maxLength":64,"example":"INV-2026-0042","description":"Your own reference, returned on the transfer and in webhooks."},"description":{"type":"string","maxLength":255},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Up to 20 string key/value pairs stored with the object.","example":{"order_id":"A-1042"}}},"required":["amount","currency","destination"],"additionalProperties":false},"Destination":{"oneOf":[{"$ref":"#/components/schemas/BankAccountDestination"},{"$ref":"#/components/schemas/MobileMoneyDestination"}],"discriminator":{"propertyName":"type","mapping":{"bank_account":"#/components/schemas/BankAccountDestination","mobile_money":"#/components/schemas/MobileMoneyDestination"}}},"BankAccountDestination":{"type":"object","properties":{"type":{"type":"string","enum":["bank_account"]},"account_number":{"type":"string","pattern":"^[A-Za-z0-9]{6,34}$","example":"GS0000000001"},"bank_code":{"type":"string","pattern":"^[A-Za-z0-9]{2,16}$","example":"GSBANK"},"account_name":{"type":"string","minLength":2,"maxLength":140,"example":"Ada Example"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"BJ"}},"required":["type","account_number","bank_code","account_name","country"]},"MobileMoneyDestination":{"type":"object","properties":{"type":{"type":"string","enum":["mobile_money"]},"phone_number":{"type":"string","pattern":"^\\+[1-9][0-9]{7,14}$","example":"+22990000001"},"network":{"type":"string","pattern":"^[A-Za-z0-9_-]{2,32}$","example":"test_network"},"account_name":{"type":"string","minLength":2,"maxLength":140,"example":"Ada Example"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"BJ"}},"required":["type","phone_number","network","account_name","country"]},"TransferList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transfer"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"CreateCardResponse":{"allOf":[{"$ref":"#/components/schemas/Card"},{"type":"object","properties":{"issuance":{"type":"object","properties":{"initial_load":{"type":"integer"},"fee":{"type":"integer"},"fee_breakdown":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["initial_load","fee","fee_breakdown"]}},"required":["issuance"]}]},"Cardholder":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L} '\\-.]+$/u","example":"Ada"},"last_name":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[\\p{L} '\\-.]+$/u","example":"Example"},"email":{"type":"string","maxLength":254,"format":"email","example":"ada@example.com"}},"required":["first_name","last_name","email"],"additionalProperties":false},"Card":{"type":"object","properties":{"id":{"type":"string","example":"card_9f8e7d6c5b4a3f2e1d0c"},"object":{"type":"string","enum":["card"]},"environment":{"$ref":"#/components/schemas/Environment"},"product":{"type":"string"},"network":{"type":"string","enum":["Visa","Mastercard"]},"currency":{"type":"string","enum":["USD"]},"status":{"type":"string","enum":["active","frozen","terminated"]},"cardholder":{"$ref":"#/components/schemas/Cardholder"},"last4":{"type":"string"},"expiry_month":{"type":"string"},"expiry_year":{"type":"string"},"balance":{"type":"integer","description":"Card balance in USD cents, as of the last operation through GLORESEND."},"reference":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"test_data":{"type":"boolean"}},"required":["id","object","environment","product","network","currency","status","cardholder","last4","expiry_month","expiry_year","balance","reference","metadata","created_at","test_data"]},"CreateCardRequest":{"type":"object","properties":{"product":{"type":"string","enum":["visa-400","visa-404","visa-493-premium","visa-493-atm","visa-536"],"description":"Card product id. See the pricing page for fees and limits.","example":"visa-404"},"cardholder":{"$ref":"#/components/schemas/Cardholder"},"initial_load":{"type":"integer","minimum":1000,"maximum":250000,"description":"Optional amount to load at creation, in USD cents ($10.00–$2,500.00). Not available for every product.","example":5000},"reference":{"type":"string","maxLength":64},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Up to 20 string key/value pairs stored with the object.","example":{"order_id":"A-1042"}}},"required":["product","cardholder"],"additionalProperties":false},"CardList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Card"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"CardOperation":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["card_operation"]},"type":{"type":"string","enum":["issue","fund","withdraw"]},"card_id":{"type":"string"},"amount":{"type":"integer"},"fee":{"type":"integer"},"fee_breakdown":{"type":"object","additionalProperties":{"type":"integer"}},"status":{"type":"string","enum":["succeeded","failed"]},"card":{"$ref":"#/components/schemas/Card"},"created_at":{"type":"string"},"test_data":{"type":"boolean"}},"required":["id","object","type","card_id","amount","fee","fee_breakdown","status","card","created_at","test_data"]},"CardAmountRequest":{"type":"object","properties":{"amount":{"type":"integer","minimum":500,"maximum":250000,"description":"Amount in USD cents.","example":2500}},"required":["amount"],"additionalProperties":false},"CardTransactionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CardTransaction"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"CardTransaction":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["card_transaction"]},"card_id":{"type":"string"},"type":{"type":"string","example":"authorization"},"status":{"type":"string","example":"succeeded"},"amount":{"type":"integer","description":"Amount in USD cents."},"currency":{"type":"string"},"merchant":{"type":"object","properties":{"name":{"type":["string","null"]},"mcc":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["name","mcc","country"]},"created_at":{"type":"string"},"test_data":{"type":"boolean"}},"required":["id","object","card_id","type","status","amount","currency","merchant","created_at","test_data"]},"CardSensitiveDetails":{"type":"object","properties":{"object":{"type":"string","enum":["card_details"]},"card_id":{"type":"string"},"number":{"type":"string"},"cvv":{"type":"string"},"expiry_month":{"type":"string"},"expiry_year":{"type":"string"},"test_data":{"type":"boolean"}},"required":["object","card_id","number","cvv","expiry_month","expiry_year","test_data"]},"FundTestBalanceRequest":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":1000000000,"description":"Amount in the currency's minor unit (for example cents). Integer.","example":125000},"currency":{"$ref":"#/components/schemas/Currency"}},"required":["amount","currency"],"additionalProperties":false},"SimulateCardAuthorization":{"type":"object","properties":{"amount":{"type":"integer","minimum":1,"maximum":250000},"merchant_name":{"type":"string","minLength":1,"maxLength":80,"default":"Test Merchant"}},"required":["amount"],"additionalProperties":false}},"parameters":{}},"paths":{"/ping":{"get":{"operationId":"ping","summary":"Verify credentials","description":"Returns the environment, organization and key that authenticated the request. Use it to confirm that a key is valid and points at the expected environment.","tags":["Core"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"The authenticated context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ping"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/currencies":{"get":{"operationId":"list-currencies","summary":"List currencies","description":"Lists the currencies the API accepts and the number of decimal places of each currency's minor unit.","tags":["Core"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Supported currencies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrencyList"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balances":{"get":{"operationId":"list-balances","summary":"List balances","description":"Returns one balance per currency wallet. In the Sandbox, every organization starts with simulated test funds; these are flagged with `test_data: true` and have no monetary value. Live balances are unavailable until a provider is authorized.","tags":["Balances"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Balances by currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceList"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transfers":{"post":{"operationId":"create-transfer","summary":"Create a transfer","description":"Sends funds from your wallet to a bank account or mobile money destination. Requires an `Idempotency-Key`. The amount and fees are reserved atomically before the provider is called; on failure the reservation is released. In the Sandbox the outcome is simulated deterministically from the destination identifier — see Sandbox testing.","tags":["Transfers"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","example":"5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11"},"required":true,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransferRequest"}}}},"responses":{"201":{"description":"The transfer that was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transfer"}}}},"400":{"description":"`validation_error`, `idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_funds`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reuse`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-transfers","summary":"List transfers","description":"Lists transfers for the environment of the API key, newest first. Paginate with `starting_after`.","tags":["Transfers"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the id of the last transfer from the previous page."},"required":false,"description":"Cursor: the id of the last transfer from the previous page.","name":"starting_after","in":"query"},{"schema":{"type":"string","enum":["processing","succeeded","failed"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of transfers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferList"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transfers/{id}":{"get":{"operationId":"get-transfer","summary":"Retrieve a transfer","description":"Retrieves a transfer by id. Transfers from other organizations or the other environment are never visible.","tags":["Transfers"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The transfer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transfer"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards":{"post":{"operationId":"create-card","summary":"Issue a card","description":"Issues a virtual card to a cardholder. The issuance fee, KYC fee and any initial load plus its top-up fee are debited from your USD wallet in the same environment. Requires an `Idempotency-Key`. In Live, the account must be activated and approved for Live.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","example":"5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11"},"required":true,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardRequest"}}}},"responses":{"201":{"description":"The issued card and the fees charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardResponse"}}}},"400":{"description":"`validation_error`, `idempotency_key_required`, `product_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_funds`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reuse`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-cards","summary":"List cards","description":"Lists the cards issued in this environment, newest first.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string","enum":["active","frozen","terminated"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardList"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}":{"get":{"operationId":"get-card","summary":"Retrieve a card","description":"Retrieves a card. The full card number and CVV are never included; see Reveal card details.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/fund":{"post":{"operationId":"fund-card","summary":"Fund a card","description":"Loads funds onto an active card ($5.00–$2,500.00 per operation). The amount plus the product's top-up fee is debited from your USD wallet. Requires an `Idempotency-Key`.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","example":"5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11"},"required":true,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardAmountRequest"}}}},"responses":{"200":{"description":"The completed operation and the updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardOperation"}}}},"400":{"description":"`validation_error`, `idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_funds`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reuse`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/withdraw":{"post":{"operationId":"withdraw-card","summary":"Withdraw from a card","description":"Moves funds from a card back to your USD wallet. At least $5.00 must remain on the card. No fee is charged. Requires an `Idempotency-Key`.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","example":"5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11"},"required":true,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardAmountRequest"}}}},"responses":{"200":{"description":"The completed operation and the updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardOperation"}}}},"400":{"description":"`validation_error`, `idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`, `insufficient_card_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reuse`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/freeze":{"post":{"operationId":"freeze-card","summary":"Freeze a card","description":"Temporarily blocks all new authorizations on the card.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/unfreeze":{"post":{"operationId":"unfreeze-card","summary":"Unfreeze a card","description":"Re-activates a frozen card.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/terminate":{"post":{"operationId":"terminate-card","summary":"Terminate a card","description":"Permanently closes the card. Withdraw the balance first, down to the $5.00 minimum the issuer keeps on each card; a larger balance returns `card_state_conflict`. In the Sandbox the remaining minimum returns to your wallet immediately; in Live it is refunded once the issuer releases it (up to 45 days).","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `activation_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`live_operations_disabled`, `provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/transactions":{"get":{"operationId":"list-card-transactions","summary":"List card transactions","description":"Lists purchases, refunds, top-ups and fees on a card, newest first. Use `page` to paginate.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"A page of card transactions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardTransactionList"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{id}/details":{"get":{"operationId":"get-card-details","summary":"Reveal card details","description":"Returns the full card number, CVV and expiry so you can display them to the cardholder. Requires the `cards:sensitive` scope. GLORESEND does not store these values. Handling card numbers brings your systems into PCI DSS scope — never log or persist them.","tags":["Cards"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Sensitive card details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSensitiveDetails"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`card_state_conflict`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`provider_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/test/fund":{"post":{"operationId":"fund-test-balance","summary":"Add test funds","description":"Sandbox only. Credits simulated funds to a Sandbox wallet so you can test large or repeated transfers. Requires an `Idempotency-Key`. Calling it against the Live base URL returns `sandbox_only`.\n\n**Sandbox only.**","tags":["Sandbox"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","example":"5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11"},"required":true,"description":"Unique key (for example a UUID) that makes retries safe. Reusing a key with a different body is rejected.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundTestBalanceRequest"}}}},"responses":{"200":{"description":"The updated test balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"`validation_error`, `idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `sandbox_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/test/cards/{id}/authorizations":{"post":{"operationId":"simulate-card-authorization","summary":"Simulate a card purchase","description":"Sandbox only. Records a simulated purchase on a Sandbox card so you can test transaction lists and balances. Declined if the card is not active or its balance is too low.\n\n**Sandbox only.**","tags":["Sandbox"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateCardAuthorization"}}}},"responses":{"201":{"description":"The simulated transaction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardTransaction"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`authentication_required`, `invalid_api_key`, `environment_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `sandbox_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}