{ "openapi": "3.1.0", "info": { "title": "Hashry Pay partner API", "version": "1.0.0", "description": "Orderless card payments, payment links, subscriptions and saved cards for Payment Integration channels. Get a token with the channel key at `POST /auth/token`, then send it as a bearer token.\n\n## Errors\n\nA refusal is a JSON body with `type`, `title`, `status` and usually `detail`. Find the reason code like this:\n\n- **In `type`** for most refusals, for example `\"type\": \"currency_mismatch\"`.\n- **In `code`** when the key may not make the call: `type` is then `/exceptions/permission_denied/`.\n- **`/exceptions//` in `type`** for `not_authenticated`, `not_found`, `throttled` and `invalid` (validation: each bad field is a key holding a list of messages).\n\nWhen `gateway_outcome_unknown` comes back, a card may have been charged: never create a new payment, refresh the one in `payment_intent_uid`.\n\n### 400 Bad Request\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `invalid` | A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`. | Fix the fields named in the body. |\n| `idempotency_key_invalid` | The Idempotency-Key header is missing or not 8 to 100 characters. | Send a key you choose, such as `order-1042-pay-1`. |\n| `currency_mismatch` | `currency` differs from the store's base currency. | Send the store's currency, or leave it out. |\n| `url_invalid` | `return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment. | Send a plain https URL. |\n| `origin_not_allowed` | The URL's origin is not on the channel's allowed return origins for this mode. | Add the origin in the Hashry admin (live and test lists are separate). |\n| `embed_origin_not_allowed` | `embed_origin` is not an exact https origin on the channel's allowed embed origins. | Add the exact origin in the Hashry admin. |\n| `customer_reference_required` | Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none. | Send the reference from your signed-in session. |\n| `saved_card_fields_immutable` | A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create. | Leave them out of the retry. |\n| `payment_link_expired` | `expires_at` is in the past. | Send a future time. |\n| `payment_link_expiry_invalid` | `expires_at` is later than a link may live (7 days by default). | Send an earlier time. |\n| `external_reference_invalid` | A reference is not a string, is empty, or is longer than 120 characters after trimming. | Send a string of 1 to 120 characters. |\n| `subscription_terms_invalid` | The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`. | Fix the plan. |\n| `zero_due_enrollment_unsupported` | Nothing is due today, for example a free trial with no setup fee. | Add a setup fee or use a paid trial. |\n\n### 401 Unauthorized\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `not_authenticated` | The access token is missing, expired or unknown, or its key was revoked. | Get a new token from POST /auth/token. |\n| `authentication_error` | The client id or secret is wrong, or the key was revoked. `title` holds the OAuth error code, `invalid_client`. A bad grant is a 400 with the same `type`: `invalid_request` or `unsupported_grant_type`. | Check the key's client id and secret, and send `grant_type: client_credentials`. |\n\n### 403 Forbidden\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `permission_denied` | The token is not a channel key's client-credentials token. | Use a token from a channel key. |\n| `secret_key_used_in_browser` | The call came from a web browser (it carried Sec-Fetch-Site). | Call Hashry from your server only, and rotate the key. Never forward a browser's Sec-Fetch-* headers. |\n| `key_revoked_browser_use` | The key was used from a browser, and the channel revokes keys used that way. | Issue a new key and call from your server. |\n| `account_unavailable` | The merchant account is suspended, closed or deleted. | Stop and contact the merchant or Hashry. |\n| `channel_not_active` | The sales channel is deleted or turned off. | The merchant turns the channel back on. |\n| `store_not_available` | The channel's store is missing or deleted. | Contact the merchant. |\n| `feature_not_enabled` | An account feature this call needs is off. The body's `features` lists them. | Ask the merchant or Hashry to turn it on. |\n| `capability_not_granted` | The key lacks the capability: `payments` or `subscriptions`. | Issue a key with the capability. |\n| `store_not_bound` | The `store_uid` sent is not this channel's store. | Leave `store_uid` out, or send the channel's store. |\n\n### 404 Not Found\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `not_found` | No object with this uid for this key's channel and mode. | Check the uid, and use the same live or test key that created it. |\n| `payment_method_not_found` | No saved card with this uid for this channel and mode. | Check the uid and the key. |\n\n### 409 Conflict\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `idempotency_conflict` | The same key was used with a different body, or a retry reused the create's key. | Resend the identical body, or use a new key for a new payment or attempt. |\n| `channel_missing` | The channel is not an enabled Payment Integration channel with a live store. | Contact the merchant. |\n| `currency_not_allowed` | The store's currency cannot be processed by the gateway. | Hashry configuration. Contact support. |\n| `limit_exceeded` | The amount, or the 24-hour count or value, is over a cap. | Lower the amount, wait, or ask the merchant or Hashry to raise the cap. |\n| `fee_processor_rate_invalid` | Hashry's fee configuration cannot price a fee the customer pays. | Hashry configuration. Contact support. |\n| `embedded_checkout_not_enabled` | The account does not have the embedded card form. | Use `presentation: redirect`, or ask Hashry to turn it on. |\n| `saved_cards_not_enabled` | Saved cards were asked for, but the account or channel switch is off. | Leave out the saved-card fields, or ask for them to be turned on. |\n| `customer_reference_unusable` | The customer reference belongs to a customer that was forgotten or removed. | Use another reference, or contact support. |\n| `store_not_ready` | The store cannot hold customers yet, so the reference cannot be used. | Contact the merchant or Hashry. |\n| `intent_already_succeeded` | The payment is already paid. | Do not retry or cancel. Refund through the merchant if needed. |\n| `intent_retry_window_closed` | The payment passed its retry window. | Start a new payment with a new key. |\n| `attempt_in_progress` | Another attempt or gateway call is running, for example while the card form can still take a card. | Wait, then read or refresh the payment. |\n| `attempt_outcome_unknown` | The payment is not `requires_payment_method`, so it cannot be retried now. | Refresh, then act on the status. |\n| `attempt_not_startable` | The attempt was already started. | Read the payment. |\n| `attempt_superseded` | A newer gateway call owns this attempt. | Read or refresh the payment, then retry if it still needs one. |\n| `cancel_not_allowed` | A card was sent or is going through, or the payment changed. Nothing changed. | Refresh and wait for the outcome. |\n| `payment_method_in_use` | A live subscription bills this card. | Change or cancel the subscription first. |\n| `payment_method_busy` | The card is in use at the gateway right now. | Try again shortly. |\n| `customer_has_active_subscriptions` | The customer still has live subscriptions. | Cancel them, then call again. |\n| `credential_revoked` | The key was revoked during the request. | Use an active key. |\n| `live_mode_required` | Subscriptions need a live key. | Use a live key. |\n| `subscription_reference_conflict` | A live enrollment or subscription already uses this `external_subscription_reference`. | Use the existing one, or cancel it first. |\n| `subscription_invalid` | The subscription is canceled or expired, so this change is not possible. | Nothing to do. Enroll again to restart. |\n| `card_update_required` | The bank said the card cannot be used. | Start an update-card session. |\n| `subscription_paused` | Hashry staff paused the subscription. | It must be resumed first. |\n| `nothing_outstanding` | No unpaid cycle to charge. | Nothing to do. |\n| `retry_already_scheduled` | A retry is already scheduled (the subscription is past_due). | Wait for its result. |\n| `subscription_terminal` | The subscription is canceled or expired. | Enroll again. |\n| `not_suspended` | Only a suspended subscription can be charged again by hand. | Read the subscription and act on its status. |\n| `billing_paused` | Billing is stopped by the account's state. | The merchant fixes the account. |\n| `billing_configuration_blocked` | Hashry's fee configuration stops billing. | Contact Hashry. |\n| `charge_in_flight` | A charge has not settled yet. | Wait, then read the subscription. |\n| `retried_too_recently` | The last attempt was less than an hour ago. | Wait, then try again. |\n\n### 429 Too Many Requests\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `throttled` | Too many requests for this key or account. | Wait the seconds in the Retry-After header, then try again. |\n\n### 502 Bad Gateway\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `gateway_unavailable` | The gateway refused or could not be reached, and nothing was charged. | Try again. A create carries `payment_intent_uid`; a retry of a cancel is safe. |\n| `gateway_outcome_unknown` | The gateway did not answer in time. A card may have been charged. | Do not create a new payment. Refresh the payment in the body's `payment_intent_uid` until the outcome is known. |\n| `gateway_redirect_rejected` | The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged. | Try again later, or contact support. |\n| `payment_method_revoke_pending` | The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal. | Nothing to do. |\n\n### 503 Service Unavailable\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `gateway_unconfigured` | Hashry's live gateway is not configured. | Try later, or contact support. |\n| `sandbox_unconfigured` | Hashry's sandbox gateway is not configured. | Try later, or contact support. |\n| `payment_link_host_unavailable` | No checkout host is configured for payment links. | Hashry configuration. Retry later with the same key. |" }, "paths": { "/auth/token": { "post": { "operationId": "oauth_token_create", "description": "OAuth 2.0 client credentials grant with a JSON body. Call it from your server only: a channel key used from a browser is refused.", "summary": "Get an access token with a channel key", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCredentialsRequest" }, "examples": { "credentials": { "summary": "A test key", "value": { "grant_type": "client_credentials", "client_id": "your-client-id", "client_secret": "hsk_test_your-client-secret" } } } } }, "required": true }, "security": [ {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthToken" }, "examples": { "token": { "summary": "An access token", "value": { "access_token": "kD9mX2qT7vRw4LpN8hBc3FyJ6sGz1Ue5", "expires_in": 36000, "token_type": "Bearer", "scope": "read write" } } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The grant is not valid. `type` is `/exceptions/authentication_error/` and `title` holds the OAuth error code: `invalid_request` or `unsupported_grant_type`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "authentication_error": { "summary": "The client id or secret is wrong, or the key was revoked. `title` holds the OAuth error code, `invalid_client`. A bad grant is a 400 with the same `type`: `invalid_request` or `unsupported_grant_type`.", "value": { "type": "/exceptions/authentication_error/", "title": "invalid_client", "status": 401, "detail": "Authentication failed. The credentials were invalid" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "authentication_error": { "summary": "The client id or secret is wrong, or the key was revoked. `title` holds the OAuth error code, `invalid_client`. A bad grant is a 400 with the same `type`: `invalid_request` or `unsupported_grant_type`.", "value": { "type": "/exceptions/authentication_error/", "title": "invalid_client", "status": 401, "detail": "Authentication failed. The credentials were invalid" } } } } }, "description": "The client id or secret is wrong. `type` is `/exceptions/authentication_error/` and `title` holds the OAuth error code, `invalid_client`.\n\n- `authentication_error`: The client id or secret is wrong, or the key was revoked. `title` holds the OAuth error code, `invalid_client`. A bad grant is a 400 with the same `type`: `invalid_request` or `unsupported_grant_type`." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } } } } }, "description": "Refused because the key was sent from a web browser. `code` is `secret_key_used_in_browser`, or `key_revoked_browser_use` for a key revoked after browser use.\n\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way." } } } }, "/v1/channel/payment-intents": { "get": { "operationId": "payment_intents_list", "description": "Use it to find a payment when you lost the create response.", "summary": "Find payment intents by your reference", "parameters": [ { "in": "query", "name": "external_reference", "schema": { "type": "string" }, "description": "Exact match on the reference you sent at create." } ], "tags": [ "Payment intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentList" }, "examples": { "found": { "summary": "Found by external_reference", "value": { "results": [ { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "redirect_issued", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "redirect_issued", "presentation": "embedded", "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null } ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } }, "post": { "operationId": "payment_intents_create", "summary": "Create a payment intent", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "8 to 100 characters. The same key with the same body returns the first result (HTTP 200) and starts nothing new. The same key with a different body is refused with 409.", "required": true } ], "tags": [ "Payment intents" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentCreateRequest" }, "examples": { "embedded": { "summary": "The card form in your page (what the SDKs send)", "value": { "amount": "2500.00", "currency": "JMD", "description": "Order 1042", "external_reference": "order-1042", "payer": { "first_name": "Alex", "email": "alex@example.com" }, "return_url": "https://shop.example.com/orders/order-1042", "cancel_url": "https://shop.example.com/cart", "presentation": "embedded", "embed_origin": "https://shop.example.com", "retry_after_decline": true } }, "redirect": { "summary": "The full payment page", "value": { "amount": "2500.00", "currency": "JMD", "description": "Order 1042", "external_reference": "order-1042", "payer": { "first_name": "Alex", "email": "alex@example.com" }, "return_url": "https://shop.example.com/orders/order-1042", "cancel_url": "https://shop.example.com/cart" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PaymentIntentCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PaymentIntentCreateRequest" } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "replay": { "summary": "The same key again: the same payment", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "redirect_issued", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "redirect_issued", "presentation": "embedded", "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null, "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "embed_url": "https://devpay.hashrytech.com/embed/bootstrap.sess7Hq2.1760436600.n0nce.SIGNATURE", "embed_expires_at": "2026-10-14T10:10:00Z", "transaction_uid": "6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f", "status_token": "hst_4qXm9TzR2vLw7KpN5hBc8DyF3sGj6Ue1", "status_token_expires_at": "2026-10-21T10:00:00Z", "status_url": "https://api.hashrytech.com/v1/public/payment-intents/3kTMd9pQxV7bWzR2nLc8Fh/status" } } } } }, "description": "Idempotent replay of an earlier create." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "created": { "summary": "Created, with the session fields", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "redirect_issued", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "redirect_issued", "presentation": "embedded", "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null, "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "embed_url": "https://devpay.hashrytech.com/embed/bootstrap.sess7Hq2.1760436600.n0nce.SIGNATURE", "embed_expires_at": "2026-10-14T10:10:00Z", "transaction_uid": "6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f", "status_token": "hst_4qXm9TzR2vLw7KpN5hBc8DyF3sGj6Ue1", "status_token_expires_at": "2026-10-21T10:00:00Z", "status_url": "https://api.hashrytech.com/v1/public/payment-intents/3kTMd9pQxV7bWzR2nLc8Fh/status" } } } } }, "description": "Created. Carries the session fields." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "amount": [ "Amount must be greater than zero." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Payment request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Payment request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "embed_origin_not_allowed": { "summary": "`embed_origin` is not an exact https origin on the channel's allowed embed origins.", "value": { "type": "embed_origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "`embed_origin` is not an exact https origin on the channel's allowed embed origins." } }, "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Payment request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "amount": [ "Amount must be greater than zero." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Payment request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Payment request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "embed_origin_not_allowed": { "summary": "`embed_origin` is not an exact https origin on the channel's allowed embed origins.", "value": { "type": "embed_origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "`embed_origin` is not an exact https origin on the channel's allowed embed origins." } }, "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Payment request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `idempotency_key_invalid`: The Idempotency-Key header is missing or not 8 to 100 characters.\n- `currency_mismatch`: `currency` differs from the store's base currency.\n- `url_invalid`: `return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.\n- `origin_not_allowed`: The URL's origin is not on the channel's allowed return origins for this mode.\n- `embed_origin_not_allowed`: `embed_origin` is not an exact https origin on the channel's allowed embed origins.\n- `customer_reference_required`: Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } }, "store_not_bound": { "summary": "The `store_uid` sent is not this channel's store.", "value": { "type": "store_not_bound", "title": "Payment request refused.", "status": 403, "detail": "The `store_uid` sent is not this channel's store." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } }, "store_not_bound": { "summary": "The `store_uid` sent is not this channel's store.", "value": { "type": "store_not_bound", "title": "Payment request refused.", "status": 403, "detail": "The `store_uid` sent is not this channel's store." } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`.\n- `store_not_bound`: The `store_uid` sent is not this channel's store." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Payment request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Payment request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Payment request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } }, "embedded_checkout_not_enabled": { "summary": "The account does not have the embedded card form.", "value": { "type": "embedded_checkout_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "The account does not have the embedded card form." } }, "saved_cards_not_enabled": { "summary": "Saved cards were asked for, but the account or channel switch is off.", "value": { "type": "saved_cards_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "Saved cards were asked for, but the account or channel switch is off." } }, "customer_reference_unusable": { "summary": "The customer reference belongs to a customer that was forgotten or removed.", "value": { "type": "customer_reference_unusable", "title": "Payment request refused.", "status": 409, "detail": "The customer reference belongs to a customer that was forgotten or removed." } }, "store_not_ready": { "summary": "The store cannot hold customers yet, so the reference cannot be used.", "value": { "type": "store_not_ready", "title": "Payment request refused.", "status": 409, "detail": "The store cannot hold customers yet, so the reference cannot be used." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Payment request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Payment request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Payment request refused.", "status": 409, "detail": "The attempt was already started.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Payment request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Payment request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Payment request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Payment request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } }, "embedded_checkout_not_enabled": { "summary": "The account does not have the embedded card form.", "value": { "type": "embedded_checkout_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "The account does not have the embedded card form." } }, "saved_cards_not_enabled": { "summary": "Saved cards were asked for, but the account or channel switch is off.", "value": { "type": "saved_cards_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "Saved cards were asked for, but the account or channel switch is off." } }, "customer_reference_unusable": { "summary": "The customer reference belongs to a customer that was forgotten or removed.", "value": { "type": "customer_reference_unusable", "title": "Payment request refused.", "status": 409, "detail": "The customer reference belongs to a customer that was forgotten or removed." } }, "store_not_ready": { "summary": "The store cannot hold customers yet, so the reference cannot be used.", "value": { "type": "store_not_ready", "title": "Payment request refused.", "status": 409, "detail": "The store cannot hold customers yet, so the reference cannot be used." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Payment request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Payment request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Payment request refused.", "status": 409, "detail": "The attempt was already started.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Payment request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `idempotency_conflict`: The same key was used with a different body, or a retry reused the create's key.\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store.\n- `currency_not_allowed`: The store's currency cannot be processed by the gateway.\n- `limit_exceeded`: The amount, or the 24-hour count or value, is over a cap.\n- `fee_processor_rate_invalid`: Hashry's fee configuration cannot price a fee the customer pays.\n- `embedded_checkout_not_enabled`: The account does not have the embedded card form.\n- `saved_cards_not_enabled`: Saved cards were asked for, but the account or channel switch is off.\n- `customer_reference_unusable`: The customer reference belongs to a customer that was forgotten or removed.\n- `store_not_ready`: The store cannot hold customers yet, so the reference cannot be used.\n- `intent_retry_window_closed`: The payment passed its retry window.\n- `attempt_in_progress`: Another attempt or gateway call is running, for example while the card form can still take a card.\n- `attempt_not_startable`: The attempt was already started.\n- `attempt_superseded`: A newer gateway call owns this attempt." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Payment request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Payment request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Payment request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Payment request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged.\n- `gateway_outcome_unknown`: The gateway did not answer in time. A card may have been charged.\n- `gateway_redirect_rejected`: The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `gateway_unconfigured`: Hashry's live gateway is not configured.\n- `sandbox_unconfigured`: Hashry's sandbox gateway is not configured." } } } }, "/v1/channel/payment-intents/{uid}": { "get": { "operationId": "payment_intents_retrieve", "summary": "Read a payment intent", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "open": { "summary": "The card form is open", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "redirect_issued", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "redirect_issued", "presentation": "embedded", "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/payment-intents/{uid}/attempts": { "post": { "operationId": "payment_intents_attempts_create", "description": "Starts a new attempt. Allowed only after a decline (`requires_payment_method`).", "summary": "Retry a declined payment", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "8 to 100 characters. The same key with the same body returns the first result (HTTP 200) and starts nothing new. The same key with a different body is refused with 409.", "required": true }, { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment intents" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAttemptCreateRequest" }, "examples": { "embedded": { "summary": "A new card form after every card was declined", "value": { "presentation": "embedded", "embed_origin": "https://shop.example.com" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PaymentAttemptCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PaymentAttemptCreateRequest" } } } }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "new_attempt": { "summary": "The payment with a new attempt and its session", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "redirect_issued", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att2Q7mN4pX2kR8vT", "attempt_number": 2, "status": "redirect_issued", "presentation": "embedded", "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk2", "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" }, { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "failed", "presentation": "embedded", "redirect_url": null, "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null, "redirect_url": "https://devpay.hashrytech.com/pay/Qm8xT2vRk1", "embed_url": "https://devpay.hashrytech.com/embed/bootstrap.sess7Hq2.1760436600.n0nce.SIGNATURE", "embed_expires_at": "2026-10-14T10:10:00Z", "transaction_uid": "6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f", "status_token": "hst_4qXm9TzR2vLw7KpN5hBc8DyF3sGj6Ue1", "status_token_expires_at": "2026-10-21T10:00:00Z", "status_url": "https://api.hashrytech.com/v1/public/payment-intents/3kTMd9pQxV7bWzR2nLc8Fh/status" } } } } }, "description": "The intent with the new session fields." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "embed_origin": [ "An embed origin is required for the embedded card form." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "embed_origin_not_allowed": { "summary": "`embed_origin` is not an exact https origin on the channel's allowed embed origins.", "value": { "type": "embed_origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "`embed_origin` is not an exact https origin on the channel's allowed embed origins." } }, "saved_card_fields_immutable": { "summary": "A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create.", "value": { "type": "saved_card_fields_immutable", "title": "Payment request refused.", "status": 400, "detail": "A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "embed_origin": [ "An embed origin is required for the embedded card form." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "embed_origin_not_allowed": { "summary": "`embed_origin` is not an exact https origin on the channel's allowed embed origins.", "value": { "type": "embed_origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "`embed_origin` is not an exact https origin on the channel's allowed embed origins." } }, "saved_card_fields_immutable": { "summary": "A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create.", "value": { "type": "saved_card_fields_immutable", "title": "Payment request refused.", "status": 400, "detail": "A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `idempotency_key_invalid`: The Idempotency-Key header is missing or not 8 to 100 characters.\n- `embed_origin_not_allowed`: `embed_origin` is not an exact https origin on the channel's allowed embed origins.\n- `saved_card_fields_immutable`: A retry sent `external_customer_reference`, `allow_save_card` or `offer_saved_cards`. They are fixed at create." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "embedded_checkout_not_enabled": { "summary": "The account does not have the embedded card form.", "value": { "type": "embedded_checkout_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "The account does not have the embedded card form." } }, "saved_cards_not_enabled": { "summary": "Saved cards were asked for, but the account or channel switch is off.", "value": { "type": "saved_cards_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "Saved cards were asked for, but the account or channel switch is off." } }, "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Payment request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Payment request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_outcome_unknown": { "summary": "The payment is not `requires_payment_method`, so it cannot be retried now.", "value": { "type": "attempt_outcome_unknown", "title": "Payment request refused.", "status": 409, "detail": "The payment is not `requires_payment_method`, so it cannot be retried now.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Payment request refused.", "status": 409, "detail": "The attempt was already started.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Payment request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "embedded_checkout_not_enabled": { "summary": "The account does not have the embedded card form.", "value": { "type": "embedded_checkout_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "The account does not have the embedded card form." } }, "saved_cards_not_enabled": { "summary": "Saved cards were asked for, but the account or channel switch is off.", "value": { "type": "saved_cards_not_enabled", "title": "Payment request refused.", "status": 409, "detail": "Saved cards were asked for, but the account or channel switch is off." } }, "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Payment request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Payment request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_outcome_unknown": { "summary": "The payment is not `requires_payment_method`, so it cannot be retried now.", "value": { "type": "attempt_outcome_unknown", "title": "Payment request refused.", "status": 409, "detail": "The payment is not `requires_payment_method`, so it cannot be retried now.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Payment request refused.", "status": 409, "detail": "The attempt was already started.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Payment request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `idempotency_conflict`: The same key was used with a different body, or a retry reused the create's key.\n- `embedded_checkout_not_enabled`: The account does not have the embedded card form.\n- `saved_cards_not_enabled`: Saved cards were asked for, but the account or channel switch is off.\n- `intent_already_succeeded`: The payment is already paid.\n- `intent_retry_window_closed`: The payment passed its retry window.\n- `attempt_in_progress`: Another attempt or gateway call is running, for example while the card form can still take a card.\n- `attempt_outcome_unknown`: The payment is not `requires_payment_method`, so it cannot be retried now.\n- `attempt_not_startable`: The attempt was already started.\n- `attempt_superseded`: A newer gateway call owns this attempt." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Payment request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Payment request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Payment request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Payment request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged.\n- `gateway_outcome_unknown`: The gateway did not answer in time. A card may have been charged.\n- `gateway_redirect_rejected`: The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Payment request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `gateway_unconfigured`: Hashry's live gateway is not configured.\n- `sandbox_unconfigured`: Hashry's sandbox gateway is not configured." } } } }, "/v1/channel/payment-intents/{uid}/cancel": { "post": { "operationId": "payment_intents_cancel", "summary": "Cancel a payment intent", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "canceled": { "summary": "Canceled before a card was sent", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "canceled", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "canceled", "presentation": "embedded", "redirect_url": null, "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "cancel_not_allowed": { "summary": "A card was sent or is going through, or the payment changed. Nothing changed.", "value": { "type": "cancel_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "A card was sent or is going through, or the payment changed. Nothing changed." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "cancel_not_allowed": { "summary": "A card was sent or is going through, or the payment changed. Nothing changed.", "value": { "type": "cancel_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "A card was sent or is going through, or the payment changed. Nothing changed." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `intent_already_succeeded`: The payment is already paid.\n- `cancel_not_allowed`: A card was sent or is going through, or the payment changed. Nothing changed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged." } } } }, "/v1/channel/payment-intents/{uid}/refresh": { "post": { "operationId": "payment_intents_refresh", "description": "Asks the gateway for the latest outcome, applies it, then returns the payment intent. Use it when a webhook is late or was missed. Hashry asks the gateway at most once every few seconds per payment; calls in between return the stored state. Never returns the card form URL.", "summary": "Ask the gateway now, then read", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" }, "examples": { "paid": { "summary": "Paid", "value": { "uid": "3kTMd9pQxV7bWzR2nLc8Fh", "status": "succeeded", "intent_kind": "payment", "delivery_method": "redirect", "link_expires_at": null, "link_revoked_at": null, "subscription_activation": null, "external_reference": "order-1042", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": true, "description": "Order 1042", "amount": "2500.00", "fee": "75.00", "customer_total": "2575.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [ { "uid": "att1Q7mN4pX2kR8vT", "attempt_number": 1, "status": "succeeded", "presentation": "embedded", "redirect_url": null, "gateway_detail": null, "expires_at": "2026-10-14T10:10:00Z", "date_created": "2026-10-14T10:00:00Z" } ], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/payment-links": { "get": { "operationId": "payment_links_list", "summary": "List payment links", "parameters": [ { "in": "query", "name": "created_after", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "created_before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "external_reference", "schema": { "type": "string" }, "description": "Exact match on the reference you sent at create." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "awaiting_customer", "canceled", "expired", "payment_review", "processing", "redirect_issued", "requires_payment_method", "succeeded" ] } } ], "tags": [ "Payment links" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkList" }, "examples": { "open": { "summary": "Open links", "value": { "results": [ { "uid": "8vXq2LmR5tNw9KpC4hYz3D", "status": "awaiting_customer", "intent_kind": "payment", "delivery_method": "payment_link", "link_expires_at": "2026-10-28T10:00:00Z", "link_revoked_at": null, "subscription_activation": null, "external_reference": "invoice-311", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": false, "description": "Invoice 311", "amount": "1800.00", "fee": "54.00", "customer_total": "1854.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": "https://devpay.hashrytech.com/i/plk_7Hq2mN4pX9kR8vT3" } ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } }, "post": { "operationId": "payment_links_create", "summary": "Create a payment link", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "8 to 100 characters. The same key with the same body returns the first result (HTTP 200) and starts nothing new. The same key with a different body is refused with 409.", "required": true } ], "tags": [ "Payment links" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" }, "examples": { "link": { "summary": "A link for an invoice", "value": { "amount": "1800.00", "currency": "JMD", "description": "Invoice 311", "external_reference": "invoice-311", "payer": { "email": "jordan@example.com" }, "return_url": "https://shop.example.com/thanks", "cancel_url": "https://shop.example.com/thanks", "expires_at": "2026-10-28T10:00:00Z" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "replay": { "summary": "The same key again", "value": { "uid": "8vXq2LmR5tNw9KpC4hYz3D", "status": "awaiting_customer", "intent_kind": "payment", "delivery_method": "payment_link", "link_expires_at": "2026-10-28T10:00:00Z", "link_revoked_at": null, "subscription_activation": null, "external_reference": "invoice-311", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": false, "description": "Invoice 311", "amount": "1800.00", "fee": "54.00", "customer_total": "1854.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": "https://devpay.hashrytech.com/i/plk_7Hq2mN4pX9kR8vT3" } } } } }, "description": "Idempotent replay of an earlier create." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "created": { "summary": "Created", "value": { "uid": "8vXq2LmR5tNw9KpC4hYz3D", "status": "awaiting_customer", "intent_kind": "payment", "delivery_method": "payment_link", "link_expires_at": "2026-10-28T10:00:00Z", "link_revoked_at": null, "subscription_activation": null, "external_reference": "invoice-311", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": false, "description": "Invoice 311", "amount": "1800.00", "fee": "54.00", "customer_total": "1854.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": "https://devpay.hashrytech.com/i/plk_7Hq2mN4pX9kR8vT3" } } } } }, "description": "Created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "amount": [ "Amount must be greater than zero." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Payment request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Payment request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "payment_link_expired": { "summary": "`expires_at` is in the past.", "value": { "type": "payment_link_expired", "title": "Payment request refused.", "status": 400, "detail": "`expires_at` is in the past." } }, "payment_link_expiry_invalid": { "summary": "`expires_at` is later than a link may live (7 days by default).", "value": { "type": "payment_link_expiry_invalid", "title": "Payment request refused.", "status": 400, "detail": "`expires_at` is later than a link may live (7 days by default)." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "amount": [ "Amount must be greater than zero." ] } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Payment request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Payment request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Payment request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Payment request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "payment_link_expired": { "summary": "`expires_at` is in the past.", "value": { "type": "payment_link_expired", "title": "Payment request refused.", "status": 400, "detail": "`expires_at` is in the past." } }, "payment_link_expiry_invalid": { "summary": "`expires_at` is later than a link may live (7 days by default).", "value": { "type": "payment_link_expiry_invalid", "title": "Payment request refused.", "status": 400, "detail": "`expires_at` is later than a link may live (7 days by default)." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `idempotency_key_invalid`: The Idempotency-Key header is missing or not 8 to 100 characters.\n- `currency_mismatch`: `currency` differs from the store's base currency.\n- `url_invalid`: `return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.\n- `origin_not_allowed`: The URL's origin is not on the channel's allowed return origins for this mode.\n- `payment_link_expired`: `expires_at` is in the past.\n- `payment_link_expiry_invalid`: `expires_at` is later than a link may live (7 days by default)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } }, "store_not_bound": { "summary": "The `store_uid` sent is not this channel's store.", "value": { "type": "store_not_bound", "title": "Payment request refused.", "status": 403, "detail": "The `store_uid` sent is not this channel's store." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } }, "store_not_bound": { "summary": "The `store_uid` sent is not this channel's store.", "value": { "type": "store_not_bound", "title": "Payment request refused.", "status": 403, "detail": "The `store_uid` sent is not this channel's store." } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`.\n- `store_not_bound`: The `store_uid` sent is not this channel's store." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Payment request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Payment request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Payment request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Payment request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Payment request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Payment request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Payment request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `idempotency_conflict`: The same key was used with a different body, or a retry reused the create's key.\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store.\n- `currency_not_allowed`: The store's currency cannot be processed by the gateway.\n- `limit_exceeded`: The amount, or the 24-hour count or value, is over a cap.\n- `fee_processor_rate_invalid`: Hashry's fee configuration cannot price a fee the customer pays." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_link_host_unavailable": { "summary": "No checkout host is configured for payment links.", "value": { "type": "payment_link_host_unavailable", "title": "Payment request refused.", "status": 503, "detail": "No checkout host is configured for payment links." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_link_host_unavailable": { "summary": "No checkout host is configured for payment links.", "value": { "type": "payment_link_host_unavailable", "title": "Payment request refused.", "status": 503, "detail": "No checkout host is configured for payment links." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `payment_link_host_unavailable`: No checkout host is configured for payment links." } } } }, "/v1/channel/payment-links/{uid}": { "get": { "operationId": "payment_links_retrieve", "summary": "Read a payment link", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment links" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "link": { "summary": "A link nobody opened yet", "value": { "uid": "8vXq2LmR5tNw9KpC4hYz3D", "status": "awaiting_customer", "intent_kind": "payment", "delivery_method": "payment_link", "link_expires_at": "2026-10-28T10:00:00Z", "link_revoked_at": null, "subscription_activation": null, "external_reference": "invoice-311", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": false, "description": "Invoice 311", "amount": "1800.00", "fee": "54.00", "customer_total": "1854.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": "https://devpay.hashrytech.com/i/plk_7Hq2mN4pX9kR8vT3" } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/payment-links/{uid}/cancel": { "post": { "operationId": "payment_links_cancel", "summary": "Cancel a payment link", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment links" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "canceled": { "summary": "Canceled: the link no longer works", "value": { "uid": "8vXq2LmR5tNw9KpC4hYz3D", "status": "canceled", "intent_kind": "payment", "delivery_method": "payment_link", "link_expires_at": "2026-10-28T10:00:00Z", "link_revoked_at": "2026-10-15T08:30:00Z", "subscription_activation": null, "external_reference": "invoice-311", "external_customer_reference": null, "external_customer_uid": null, "allow_save_card": false, "offer_saved_cards": false, "retry_after_decline": false, "description": "Invoice 311", "amount": "1800.00", "fee": "54.00", "customer_total": "1854.00", "currency": "JMD", "mode": "test", "amount_refunded": "0.00", "refunds": [], "attention_required": false, "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "attempts": [], "captures": [], "application": null, "store": null, "review_reason": null, "payer": null, "payment_method": null, "payment_url": null } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "cancel_not_allowed": { "summary": "A card was sent or is going through, or the payment changed. Nothing changed.", "value": { "type": "cancel_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "A card was sent or is going through, or the payment changed. Nothing changed." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "intent_already_succeeded": { "summary": "The payment is already paid.", "value": { "type": "intent_already_succeeded", "title": "Payment request refused.", "status": 409, "detail": "The payment is already paid." } }, "cancel_not_allowed": { "summary": "A card was sent or is going through, or the payment changed. Nothing changed.", "value": { "type": "cancel_not_allowed", "title": "Payment request refused.", "status": 409, "detail": "A card was sent or is going through, or the payment changed. Nothing changed." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `intent_already_succeeded`: The payment is already paid.\n- `cancel_not_allowed`: A card was sent or is going through, or the payment changed. Nothing changed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Payment request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged." } } } }, "/v1/channel/payment-methods": { "get": { "operationId": "payment_methods_list", "summary": "List a customer's saved cards", "parameters": [ { "in": "query", "name": "external_customer_reference", "schema": { "type": "string" }, "description": "Your id for the customer, from your own signed-in session.", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Payment methods" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPaymentMethodList" }, "examples": { "cards": { "summary": "One saved card", "value": { "count": 1, "from": 1, "to": 1, "state": { "external_customer_reference": [ "cust-77" ] }, "current": "https://api.hashrytech.com/v1/channel/payment-methods?external_customer_reference=cust-77", "next": null, "previous": null, "results": [ { "uid": "2wLp7XqN9mRc4KtV8hBz5G", "card_brand": "Visa", "card_last4": "0071", "card_exp_month": 12, "card_exp_year": 2030, "status": "active", "revocation_pending": false, "date_created": "2026-09-30T15:22:10Z" } ] } } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } } } } }, "description": "The request is not valid.\n\n- `customer_reference_required`: Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.\n- `external_reference_invalid`: A reference is not a string, is empty, or is longer than 120 characters after trimming." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/payment-methods/{uid}": { "delete": { "operationId": "payment_methods_delete", "summary": "Remove a saved card", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Payment methods" ], "security": [ { "oauth2": [] } ], "responses": { "204": { "description": "Removed, or already removed." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_method_not_found": { "summary": "No saved card with this uid for this channel and mode.", "value": { "type": "payment_method_not_found", "title": "Request refused.", "status": 404, "detail": "No saved card with this uid for this channel and mode." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_method_not_found": { "summary": "No saved card with this uid for this channel and mode.", "value": { "type": "payment_method_not_found", "title": "Request refused.", "status": 404, "detail": "No saved card with this uid for this channel and mode." } } } } }, "description": "Not found for this key.\n\n- `payment_method_not_found`: No saved card with this uid for this channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "payment_method_in_use": { "summary": "A live subscription bills this card.", "value": { "type": "payment_method_in_use", "title": "Request refused.", "status": 409, "detail": "A live subscription bills this card." } }, "payment_method_busy": { "summary": "The card is in use at the gateway right now.", "value": { "type": "payment_method_busy", "title": "Request refused.", "status": 409, "detail": "The card is in use at the gateway right now." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "payment_method_in_use": { "summary": "A live subscription bills this card.", "value": { "type": "payment_method_in_use", "title": "Request refused.", "status": 409, "detail": "A live subscription bills this card." } }, "payment_method_busy": { "summary": "The card is in use at the gateway right now.", "value": { "type": "payment_method_busy", "title": "Request refused.", "status": 409, "detail": "The card is in use at the gateway right now." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store.\n- `payment_method_in_use`: A live subscription bills this card.\n- `payment_method_busy`: The card is in use at the gateway right now." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_method_revoke_pending": { "summary": "The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal.", "value": { "type": "payment_method_revoke_pending", "title": "Request refused.", "status": 502, "detail": "The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_method_revoke_pending": { "summary": "The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal.", "value": { "type": "payment_method_revoke_pending", "title": "Request refused.", "status": 502, "detail": "The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal." } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `payment_method_revoke_pending`: The gateway has not confirmed the removal. The card is already unusable and Hashry finishes the removal." } } } }, "/v1/channel/payment-methods/forget-customer": { "post": { "operationId": "payment_methods_forget_customer", "description": "Call it when the person deletes their account with you. With a live key, Hashry removes every saved card (live and test) and retires the reference; it is refused with 409 `customer_has_active_subscriptions` while a subscription bills them. With a test key, only the test cards are removed. One call is enough: a removal the gateway has not confirmed yet finishes later (202, `cards_pending`). A repeat, or a reference Hashry never saw, is a quiet success.", "summary": "Forget a customer and remove their cards", "tags": [ "Payment methods" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetCustomerRequest" }, "examples": { "customer": { "summary": "Forget one customer", "value": { "external_customer_reference": "cust-77" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ForgetCustomerRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ForgetCustomerRequest" } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetCustomerResult" }, "examples": { "done": { "summary": "Done", "value": { "external_customer_reference": "cust-77", "customer_found": true, "customer_forgotten": true, "cards_revoked": 1, "cards_pending": 0 } } } } }, "description": "Done." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetCustomerResult" }, "examples": { "pending": { "summary": "A card removal waits for the gateway", "value": { "external_customer_reference": "cust-77", "customer_found": true, "customer_forgotten": true, "cards_revoked": 0, "cards_pending": 1 } } } } }, "description": "Accepted. Some removals wait for the gateway (`cards_pending`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "external_customer_reference": [ "This field is required." ] } }, "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "external_customer_reference": [ "This field is required." ] } }, "customer_reference_required": { "summary": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.", "value": { "type": "customer_reference_required", "title": "Request refused.", "status": 400, "detail": "Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `customer_reference_required`: Saved-card flags were sent without `external_customer_reference`, or a saved-card call has none.\n- `external_reference_invalid`: A reference is not a string, is empty, or is longer than 120 characters after trimming." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "customer_has_active_subscriptions": { "summary": "The customer still has live subscriptions.", "value": { "type": "customer_has_active_subscriptions", "title": "Request refused.", "status": 409, "detail": "The customer still has live subscriptions." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "customer_has_active_subscriptions": { "summary": "The customer still has live subscriptions.", "value": { "type": "customer_has_active_subscriptions", "title": "Request refused.", "status": 409, "detail": "The customer still has live subscriptions." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store.\n- `customer_has_active_subscriptions`: The customer still has live subscriptions." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/self": { "get": { "operationId": "channel_self_retrieve", "summary": "Read the channel behind this key", "tags": [ "Channel" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelSelf" }, "examples": { "channel": { "summary": "A test key", "value": { "channel": { "uid": "chn_4Kp7mX2qT9vR", "name": "Mr Breakfast online", "kind": "payment_integration" }, "store": { "uid": "str_8Hq2mN4pX7kR", "name": "Mr Breakfast", "base_currency": "JMD" }, "mode": "test", "capabilities": [ "payments", "subscriptions" ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscription-intents": { "get": { "operationId": "subscription_intents_list", "description": "Use it to find an enrollment when you lost the create response.", "summary": "Find enrollments by your subscription reference", "parameters": [ { "in": "query", "name": "external_subscription_reference", "schema": { "type": "string" } } ], "tags": [ "Subscription intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIntentList" }, "examples": { "found": { "summary": "Found by your reference", "value": { "results": [ { "uid": "5nRw8KcT2mXq7LpV9hBz4F", "status": "redirect_issued", "intent_kind": "subscription_enrollment", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "amount_due_today": "3000.00", "fee": "90.00", "customer_total": "3090.00", "currency": "JMD", "plan": { "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "first_payment": { "amount": "3000.00", "fee_amount": "90.00", "customer_total": "3090.00" }, "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cancellation_terms_version": "2026-09-01" }, "subscription_activation_status": "pending", "activation_action": null, "subscription_uid": null, "enrollment_terminal_reason": null, "amount_refunded": "0.00", "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z" } ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } }, "post": { "operationId": "subscription_intents_create", "summary": "Enroll a customer in a subscription", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "8 to 100 characters. The same key with the same body returns the first result (HTTP 200) and starts nothing new. The same key with a different body is refused with 409.", "required": true } ], "tags": [ "Subscription intents" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIntentCreateRequest" }, "examples": { "monthly": { "summary": "A monthly plan", "value": { "plan": { "name": "Coffee club", "description": "One bag of coffee a month", "recurring_amount": "3000.00", "billing_interval_unit": "month", "billing_interval_count": 1 }, "payer": { "first_name": "Alex", "email": "alex@example.com" }, "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "currency": "JMD", "return_url": "https://shop.example.com/account/subscriptions", "cancel_url": "https://shop.example.com/account/subscriptions" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SubscriptionIntentCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SubscriptionIntentCreateRequest" } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIntent" }, "examples": { "replay": { "summary": "The same key again", "value": { "uid": "5nRw8KcT2mXq7LpV9hBz4F", "status": "redirect_issued", "intent_kind": "subscription_enrollment", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "amount_due_today": "3000.00", "fee": "90.00", "customer_total": "3090.00", "currency": "JMD", "plan": { "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "first_payment": { "amount": "3000.00", "fee_amount": "90.00", "customer_total": "3090.00" }, "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cancellation_terms_version": "2026-09-01" }, "subscription_activation_status": "pending", "activation_action": null, "subscription_uid": null, "enrollment_terminal_reason": null, "amount_refunded": "0.00", "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "redirect_url": "https://devpay.hashrytech.com/enroll/enr_7Hq2mN4pX9" } } } } }, "description": "Idempotent replay of an earlier create." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIntent" }, "examples": { "created": { "summary": "Created", "value": { "uid": "5nRw8KcT2mXq7LpV9hBz4F", "status": "redirect_issued", "intent_kind": "subscription_enrollment", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "amount_due_today": "3000.00", "fee": "90.00", "customer_total": "3090.00", "currency": "JMD", "plan": { "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "first_payment": { "amount": "3000.00", "fee_amount": "90.00", "customer_total": "3090.00" }, "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cancellation_terms_version": "2026-09-01" }, "subscription_activation_status": "pending", "activation_action": null, "subscription_uid": null, "enrollment_terminal_reason": null, "amount_refunded": "0.00", "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z", "redirect_url": "https://devpay.hashrytech.com/enroll/enr_7Hq2mN4pX9" } } } } }, "description": "Created. Carries `redirect_url`." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "plan": { "recurring_amount": [ "A valid number is required." ] } } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Subscription request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Subscription request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Subscription request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Subscription request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Subscription request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } }, "subscription_terms_invalid": { "summary": "The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`.", "value": { "type": "subscription_terms_invalid", "title": "Subscription request refused.", "status": 400, "detail": "The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`." } }, "zero_due_enrollment_unsupported": { "summary": "Nothing is due today, for example a free trial with no setup fee.", "value": { "type": "zero_due_enrollment_unsupported", "title": "Subscription request refused.", "status": 400, "detail": "Nothing is due today, for example a free trial with no setup fee." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "plan": { "recurring_amount": [ "A valid number is required." ] } } }, "idempotency_key_invalid": { "summary": "The Idempotency-Key header is missing or not 8 to 100 characters.", "value": { "type": "idempotency_key_invalid", "title": "Subscription request refused.", "status": 400, "detail": "The Idempotency-Key header is missing or not 8 to 100 characters." } }, "currency_mismatch": { "summary": "`currency` differs from the store's base currency.", "value": { "type": "currency_mismatch", "title": "Subscription request refused.", "status": 400, "detail": "`currency` differs from the store's base currency." } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Subscription request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Subscription request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } }, "external_reference_invalid": { "summary": "A reference is not a string, is empty, or is longer than 120 characters after trimming.", "value": { "type": "external_reference_invalid", "title": "Subscription request refused.", "status": 400, "detail": "A reference is not a string, is empty, or is longer than 120 characters after trimming." } }, "subscription_terms_invalid": { "summary": "The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`.", "value": { "type": "subscription_terms_invalid", "title": "Subscription request refused.", "status": 400, "detail": "The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`." } }, "zero_due_enrollment_unsupported": { "summary": "Nothing is due today, for example a free trial with no setup fee.", "value": { "type": "zero_due_enrollment_unsupported", "title": "Subscription request refused.", "status": 400, "detail": "Nothing is due today, for example a free trial with no setup fee." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `idempotency_key_invalid`: The Idempotency-Key header is missing or not 8 to 100 characters.\n- `currency_mismatch`: `currency` differs from the store's base currency.\n- `url_invalid`: `return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.\n- `origin_not_allowed`: The URL's origin is not on the channel's allowed return origins for this mode.\n- `external_reference_invalid`: A reference is not a string, is empty, or is longer than 120 characters after trimming.\n- `subscription_terms_invalid`: The plan's terms do not fit together, for example `fixed_cycles` without `term_cycle_count`.\n- `zero_due_enrollment_unsupported`: Nothing is due today, for example a free trial with no setup fee." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Subscription request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Subscription request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Subscription request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Subscription request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Subscription request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } }, "customer_reference_unusable": { "summary": "The customer reference belongs to a customer that was forgotten or removed.", "value": { "type": "customer_reference_unusable", "title": "Subscription request refused.", "status": 409, "detail": "The customer reference belongs to a customer that was forgotten or removed." } }, "store_not_ready": { "summary": "The store cannot hold customers yet, so the reference cannot be used.", "value": { "type": "store_not_ready", "title": "Subscription request refused.", "status": 409, "detail": "The store cannot hold customers yet, so the reference cannot be used." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Subscription request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Subscription request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Subscription request refused.", "status": 409, "detail": "The attempt was already started.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Subscription request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "credential_revoked": { "summary": "The key was revoked during the request.", "value": { "type": "credential_revoked", "title": "Subscription request refused.", "status": 409, "detail": "The key was revoked during the request." } }, "live_mode_required": { "summary": "Subscriptions need a live key.", "value": { "type": "live_mode_required", "title": "Subscription request refused.", "status": 409, "detail": "Subscriptions need a live key." } }, "subscription_reference_conflict": { "summary": "A live enrollment or subscription already uses this `external_subscription_reference`.", "value": { "type": "subscription_reference_conflict", "title": "Subscription request refused.", "status": 409, "detail": "A live enrollment or subscription already uses this `external_subscription_reference`." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotency_conflict": { "summary": "The same key was used with a different body, or a retry reused the create's key.", "value": { "type": "idempotency_conflict", "title": "Subscription request refused.", "status": 409, "detail": "The same key was used with a different body, or a retry reused the create's key." } }, "channel_missing": { "summary": "The channel is not an enabled Payment Integration channel with a live store.", "value": { "type": "channel_missing", "title": "Subscription request refused.", "status": 409, "detail": "The channel is not an enabled Payment Integration channel with a live store." } }, "currency_not_allowed": { "summary": "The store's currency cannot be processed by the gateway.", "value": { "type": "currency_not_allowed", "title": "Subscription request refused.", "status": 409, "detail": "The store's currency cannot be processed by the gateway." } }, "limit_exceeded": { "summary": "The amount, or the 24-hour count or value, is over a cap.", "value": { "type": "limit_exceeded", "title": "Subscription request refused.", "status": 409, "detail": "The amount, or the 24-hour count or value, is over a cap." } }, "fee_processor_rate_invalid": { "summary": "Hashry's fee configuration cannot price a fee the customer pays.", "value": { "type": "fee_processor_rate_invalid", "title": "Subscription request refused.", "status": 409, "detail": "Hashry's fee configuration cannot price a fee the customer pays." } }, "customer_reference_unusable": { "summary": "The customer reference belongs to a customer that was forgotten or removed.", "value": { "type": "customer_reference_unusable", "title": "Subscription request refused.", "status": 409, "detail": "The customer reference belongs to a customer that was forgotten or removed." } }, "store_not_ready": { "summary": "The store cannot hold customers yet, so the reference cannot be used.", "value": { "type": "store_not_ready", "title": "Subscription request refused.", "status": 409, "detail": "The store cannot hold customers yet, so the reference cannot be used." } }, "intent_retry_window_closed": { "summary": "The payment passed its retry window.", "value": { "type": "intent_retry_window_closed", "title": "Subscription request refused.", "status": 409, "detail": "The payment passed its retry window." } }, "attempt_in_progress": { "summary": "Another attempt or gateway call is running, for example while the card form can still take a card.", "value": { "type": "attempt_in_progress", "title": "Subscription request refused.", "status": 409, "detail": "Another attempt or gateway call is running, for example while the card form can still take a card.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "attempt_not_startable": { "summary": "The attempt was already started.", "value": { "type": "attempt_not_startable", "title": "Subscription request refused.", "status": 409, "detail": "The attempt was already started.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "attempt_superseded": { "summary": "A newer gateway call owns this attempt.", "value": { "type": "attempt_superseded", "title": "Subscription request refused.", "status": 409, "detail": "A newer gateway call owns this attempt.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "credential_revoked": { "summary": "The key was revoked during the request.", "value": { "type": "credential_revoked", "title": "Subscription request refused.", "status": 409, "detail": "The key was revoked during the request." } }, "live_mode_required": { "summary": "Subscriptions need a live key.", "value": { "type": "live_mode_required", "title": "Subscription request refused.", "status": 409, "detail": "Subscriptions need a live key." } }, "subscription_reference_conflict": { "summary": "A live enrollment or subscription already uses this `external_subscription_reference`.", "value": { "type": "subscription_reference_conflict", "title": "Subscription request refused.", "status": 409, "detail": "A live enrollment or subscription already uses this `external_subscription_reference`." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `idempotency_conflict`: The same key was used with a different body, or a retry reused the create's key.\n- `channel_missing`: The channel is not an enabled Payment Integration channel with a live store.\n- `currency_not_allowed`: The store's currency cannot be processed by the gateway.\n- `limit_exceeded`: The amount, or the 24-hour count or value, is over a cap.\n- `fee_processor_rate_invalid`: Hashry's fee configuration cannot price a fee the customer pays.\n- `customer_reference_unusable`: The customer reference belongs to a customer that was forgotten or removed.\n- `store_not_ready`: The store cannot hold customers yet, so the reference cannot be used.\n- `intent_retry_window_closed`: The payment passed its retry window.\n- `attempt_in_progress`: Another attempt or gateway call is running, for example while the card form can still take a card.\n- `attempt_not_startable`: The attempt was already started.\n- `attempt_superseded`: A newer gateway call owns this attempt.\n- `credential_revoked`: The key was revoked during the request.\n- `live_mode_required`: Subscriptions need a live key.\n- `subscription_reference_conflict`: A live enrollment or subscription already uses this `external_subscription_reference`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Subscription request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Subscription request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "gateway_outcome_unknown": { "summary": "The gateway did not answer in time. A card may have been charged.", "value": { "type": "gateway_outcome_unknown", "title": "Subscription request refused.", "status": 502, "detail": "The gateway did not answer in time. A card may have been charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "gateway_redirect_rejected": { "summary": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "value": { "type": "gateway_redirect_rejected", "title": "Subscription request refused.", "status": 502, "detail": "The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged.\n- `gateway_outcome_unknown`: The gateway did not answer in time. A card may have been charged.\n- `gateway_redirect_rejected`: The gateway returned a payment page Hashry will not use. The attempt failed and nothing was charged." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured.", "subscription_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F" } }, "sandbox_unconfigured": { "summary": "Hashry's sandbox gateway is not configured.", "value": { "type": "sandbox_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's sandbox gateway is not configured." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `gateway_unconfigured`: Hashry's live gateway is not configured.\n- `sandbox_unconfigured`: Hashry's sandbox gateway is not configured." } } } }, "/v1/channel/subscription-intents/{uid}": { "get": { "operationId": "subscription_intents_retrieve", "summary": "Read an enrollment", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscription intents" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionIntent" }, "examples": { "activated": { "summary": "Paid and activated", "value": { "uid": "5nRw8KcT2mXq7LpV9hBz4F", "status": "succeeded", "intent_kind": "subscription_enrollment", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "amount_due_today": "3000.00", "fee": "90.00", "customer_total": "3090.00", "currency": "JMD", "plan": { "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "first_payment": { "amount": "3000.00", "fee_amount": "90.00", "customer_total": "3090.00" }, "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cancellation_terms_version": "2026-09-01" }, "subscription_activation_status": "activated", "activation_action": null, "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "enrollment_terminal_reason": null, "amount_refunded": "0.00", "retry_until": "2026-10-21T10:00:00Z", "date_created": "2026-10-14T10:00:00Z" } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions": { "get": { "operationId": "subscriptions_list", "description": "Live keys only. A test key gets an empty list.", "summary": "List subscriptions", "parameters": [ { "in": "query", "name": "external_reference", "schema": { "type": "string" }, "description": "Your subscription reference." }, { "in": "query", "name": "external_subscription_reference", "schema": { "type": "string" }, "description": "Same as `external_reference`. Used when that one is absent." } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionList" }, "examples": { "active": { "summary": "One active subscription", "value": { "results": [ { "uid": "9cHm4TqW7xRn2KvB5pLz8D", "status": "active", "external_subscription_reference": "sub-77-coffee", "external_customer_reference": "cust-77", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cycles_completed": 1, "cycles_waived": 0, "cancel_at_period_end": false, "cancel_requested_at": null, "effective_end_at": null, "canceled_at": null, "expired_at": null, "started_at": "2026-10-14T10:02:31Z", "current_period_start_at": "2026-10-14T10:02:31Z", "current_period_end_at": "2026-11-14T10:02:31Z", "next_charge_at": "2026-11-14T10:02:31Z", "next_retry_at": null, "terms_fingerprint": "9f2b7c41e0a3d5b8", "accepted_terms_at": "2026-10-14T10:01:58Z", "billing_hold": null, "card": { "brand": "Visa", "last4": "0071", "exp_month": 12, "exp_year": 2030, "status": "active" } } ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions/{uid}": { "get": { "operationId": "subscriptions_retrieve", "summary": "Read a subscription", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "active": { "summary": "Active", "value": { "uid": "9cHm4TqW7xRn2KvB5pLz8D", "status": "active", "external_subscription_reference": "sub-77-coffee", "external_customer_reference": "cust-77", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cycles_completed": 1, "cycles_waived": 0, "cancel_at_period_end": false, "cancel_requested_at": null, "effective_end_at": null, "canceled_at": null, "expired_at": null, "started_at": "2026-10-14T10:02:31Z", "current_period_start_at": "2026-10-14T10:02:31Z", "current_period_end_at": "2026-11-14T10:02:31Z", "next_charge_at": "2026-11-14T10:02:31Z", "next_retry_at": null, "terms_fingerprint": "9f2b7c41e0a3d5b8", "accepted_terms_at": "2026-10-14T10:01:58Z", "billing_hold": null, "card": { "brand": "Visa", "last4": "0071", "exp_month": 12, "exp_year": 2030, "status": "active" } } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions/{uid}/cancel": { "post": { "operationId": "subscriptions_cancel", "description": "Schedules the end of the subscription. The customer keeps what they paid for until the period ends, and nothing more is charged. You get `subscription.cancellation_scheduled` now and `subscription.canceled` when the period ends. Before then, uncancel undoes it.", "summary": "Cancel at the end of the paid period", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "scheduled": { "summary": "Ends at the end of the paid period", "value": { "uid": "9cHm4TqW7xRn2KvB5pLz8D", "status": "active", "external_subscription_reference": "sub-77-coffee", "external_customer_reference": "cust-77", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cycles_completed": 1, "cycles_waived": 0, "cancel_at_period_end": true, "cancel_requested_at": "2026-10-20T09:00:00Z", "effective_end_at": "2026-11-14T10:02:31Z", "canceled_at": null, "expired_at": null, "started_at": "2026-10-14T10:02:31Z", "current_period_start_at": "2026-10-14T10:02:31Z", "current_period_end_at": "2026-11-14T10:02:31Z", "next_charge_at": null, "next_retry_at": null, "terms_fingerprint": "9f2b7c41e0a3d5b8", "accepted_terms_at": "2026-10-14T10:01:58Z", "billing_hold": null, "card": { "brand": "Visa", "last4": "0071", "exp_month": 12, "exp_year": 2030, "status": "active" } } } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `subscription_invalid`: The subscription is canceled or expired, so this change is not possible." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions/{uid}/charges": { "get": { "operationId": "subscriptions_charges_list", "summary": "List a subscription's charges", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChargeList" }, "examples": { "charges": { "summary": "The first cycle, paid", "value": { "results": [ { "uid": "chg_3Wm8qT2vR7kN", "cycle_uid": "cyc_2026_10", "attempt_number": 1, "status": "success", "amount": "3090.00", "currency": "JMD", "due_at": "2026-10-14T10:02:31Z", "period_start": "2026-10-14T10:02:31Z", "period_end": "2026-11-14T10:02:31Z", "completed_at": "2026-10-14T10:02:31Z", "failure_category": null, "retryable": false, "refund_summary": { "amount_refunded": "0.00", "refund_count": 0 } } ] } } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions/{uid}/retry-now": { "post": { "operationId": "subscriptions_retry_now", "description": "Charges the unpaid cycle once more, on the card on file, for the same amount. Use it when the card was never the problem: a bank outage, or an issuer hold that has since cleared. If the card itself was refused, start an update-card session instead. No Idempotency-Key: a repeat call gets 409 `retry_already_scheduled`. `charge_created` says whether a charge was made.", "summary": "Charge a suspended subscription's unpaid cycle again", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRetryResult" }, "examples": { "retried": { "summary": "Charged again and paid", "value": { "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "charge_created": true, "status": "active" } } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "card_update_required": { "summary": "The bank said the card cannot be used.", "value": { "type": "card_update_required", "title": "Subscription request refused.", "status": 409, "detail": "The bank said the card cannot be used." } }, "subscription_paused": { "summary": "Hashry staff paused the subscription.", "value": { "type": "subscription_paused", "title": "Subscription request refused.", "status": 409, "detail": "Hashry staff paused the subscription." } }, "nothing_outstanding": { "summary": "No unpaid cycle to charge.", "value": { "type": "nothing_outstanding", "title": "Subscription request refused.", "status": 409, "detail": "No unpaid cycle to charge." } }, "retry_already_scheduled": { "summary": "A retry is already scheduled (the subscription is past_due).", "value": { "type": "retry_already_scheduled", "title": "Subscription request refused.", "status": 409, "detail": "A retry is already scheduled (the subscription is past_due)." } }, "subscription_terminal": { "summary": "The subscription is canceled or expired.", "value": { "type": "subscription_terminal", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired." } }, "not_suspended": { "summary": "Only a suspended subscription can be charged again by hand.", "value": { "type": "not_suspended", "title": "Subscription request refused.", "status": 409, "detail": "Only a suspended subscription can be charged again by hand." } }, "billing_paused": { "summary": "Billing is stopped by the account's state.", "value": { "type": "billing_paused", "title": "Subscription request refused.", "status": 409, "detail": "Billing is stopped by the account's state." } }, "billing_configuration_blocked": { "summary": "Hashry's fee configuration stops billing.", "value": { "type": "billing_configuration_blocked", "title": "Subscription request refused.", "status": 409, "detail": "Hashry's fee configuration stops billing." } }, "charge_in_flight": { "summary": "A charge has not settled yet.", "value": { "type": "charge_in_flight", "title": "Subscription request refused.", "status": 409, "detail": "A charge has not settled yet." } }, "retried_too_recently": { "summary": "The last attempt was less than an hour ago.", "value": { "type": "retried_too_recently", "title": "Subscription request refused.", "status": 409, "detail": "The last attempt was less than an hour ago." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "card_update_required": { "summary": "The bank said the card cannot be used.", "value": { "type": "card_update_required", "title": "Subscription request refused.", "status": 409, "detail": "The bank said the card cannot be used." } }, "subscription_paused": { "summary": "Hashry staff paused the subscription.", "value": { "type": "subscription_paused", "title": "Subscription request refused.", "status": 409, "detail": "Hashry staff paused the subscription." } }, "nothing_outstanding": { "summary": "No unpaid cycle to charge.", "value": { "type": "nothing_outstanding", "title": "Subscription request refused.", "status": 409, "detail": "No unpaid cycle to charge." } }, "retry_already_scheduled": { "summary": "A retry is already scheduled (the subscription is past_due).", "value": { "type": "retry_already_scheduled", "title": "Subscription request refused.", "status": 409, "detail": "A retry is already scheduled (the subscription is past_due)." } }, "subscription_terminal": { "summary": "The subscription is canceled or expired.", "value": { "type": "subscription_terminal", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired." } }, "not_suspended": { "summary": "Only a suspended subscription can be charged again by hand.", "value": { "type": "not_suspended", "title": "Subscription request refused.", "status": 409, "detail": "Only a suspended subscription can be charged again by hand." } }, "billing_paused": { "summary": "Billing is stopped by the account's state.", "value": { "type": "billing_paused", "title": "Subscription request refused.", "status": 409, "detail": "Billing is stopped by the account's state." } }, "billing_configuration_blocked": { "summary": "Hashry's fee configuration stops billing.", "value": { "type": "billing_configuration_blocked", "title": "Subscription request refused.", "status": 409, "detail": "Hashry's fee configuration stops billing." } }, "charge_in_flight": { "summary": "A charge has not settled yet.", "value": { "type": "charge_in_flight", "title": "Subscription request refused.", "status": 409, "detail": "A charge has not settled yet." } }, "retried_too_recently": { "summary": "The last attempt was less than an hour ago.", "value": { "type": "retried_too_recently", "title": "Subscription request refused.", "status": 409, "detail": "The last attempt was less than an hour ago." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `card_update_required`: The bank said the card cannot be used.\n- `subscription_paused`: Hashry staff paused the subscription.\n- `nothing_outstanding`: No unpaid cycle to charge.\n- `retry_already_scheduled`: A retry is already scheduled (the subscription is past_due).\n- `subscription_terminal`: The subscription is canceled or expired.\n- `not_suspended`: Only a suspended subscription can be charged again by hand.\n- `billing_paused`: Billing is stopped by the account's state.\n- `billing_configuration_blocked`: Hashry's fee configuration stops billing.\n- `charge_in_flight`: A charge has not settled yet.\n- `retried_too_recently`: The last attempt was less than an hour ago." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `gateway_unconfigured`: Hashry's live gateway is not configured." } } } }, "/v1/channel/subscriptions/{uid}/uncancel": { "post": { "operationId": "subscriptions_uncancel", "description": "Undoes a scheduled cancellation, so billing goes on as before. A canceled or expired subscription cannot be restored: enroll the customer again.", "summary": "Remove a scheduled cancellation", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "active": { "summary": "Back to renewing", "value": { "uid": "9cHm4TqW7xRn2KvB5pLz8D", "status": "active", "external_subscription_reference": "sub-77-coffee", "external_customer_reference": "cust-77", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "plan_name": "Coffee club", "description": "One bag of coffee a month", "currency": "JMD", "recurring_amount": "3000.00", "setup_fee_amount": "0.00", "billing_interval_unit": "month", "billing_interval_count": 1, "trial_mode": "none", "trial_interval_unit": null, "trial_interval_count": null, "trial_amount": "0.00", "term_mode": "evergreen", "term_cycle_count": null, "cycles_completed": 1, "cycles_waived": 0, "cancel_at_period_end": false, "cancel_requested_at": null, "effective_end_at": null, "canceled_at": null, "expired_at": null, "started_at": "2026-10-14T10:02:31Z", "current_period_start_at": "2026-10-14T10:02:31Z", "current_period_end_at": "2026-11-14T10:02:31Z", "next_charge_at": "2026-11-14T10:02:31Z", "next_retry_at": null, "terms_fingerprint": "9f2b7c41e0a3d5b8", "accepted_terms_at": "2026-10-14T10:01:58Z", "billing_hold": null, "card": { "brand": "Visa", "last4": "0071", "exp_month": 12, "exp_year": 2030, "status": "active" } } } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `subscription_invalid`: The subscription is canceled or expired, so this change is not possible." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } }, "/v1/channel/subscriptions/{uid}/update-card-session": { "post": { "operationId": "subscriptions_update_card_session_create", "description": "Returns a Hashry page where the customer enters a new card for this subscription. Send the customer to `update_url` before `expires_at`. `return_url` and `cancel_url` must be on the channel's allowed return origins. While a session is open, a new call returns it with 200.", "summary": "Start a hosted card-update session", "parameters": [ { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdateSessionCreateRequest" }, "examples": { "default": { "summary": "Send the customer back to their account", "value": { "return_url": "https://shop.example.com/account/subscriptions", "cancel_url": "https://shop.example.com/account/subscriptions" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CardUpdateSessionCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CardUpdateSessionCreateRequest" } } } }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdateSession" }, "examples": { "existing": { "summary": "An open session that already existed", "value": { "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "update_url": "https://devpay.hashrytech.com/update-card/ucs_7Hq2mN4pX9", "expires_at": "2026-10-15T10:00:00Z", "status": "open" } } } } }, "description": "An open session that already existed." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdateSession" }, "examples": { "created": { "summary": "Created", "value": { "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "update_url": "https://devpay.hashrytech.com/update-card/ucs_7Hq2mN4pX9", "expires_at": "2026-10-15T10:00:00Z", "status": "open" } } } } }, "description": "Created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "return_url": [ "Enter a valid URL." ] } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Subscription request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Subscription request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "summary": "A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.", "value": { "type": "/exceptions/invalid/", "title": "Invalid input.", "status": 400, "return_url": [ "Enter a valid URL." ] } }, "url_invalid": { "summary": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.", "value": { "type": "url_invalid", "title": "Subscription request refused.", "status": 400, "detail": "`return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment." } }, "origin_not_allowed": { "summary": "The URL's origin is not on the channel's allowed return origins for this mode.", "value": { "type": "origin_not_allowed", "title": "Subscription request refused.", "status": 400, "detail": "The URL's origin is not on the channel's allowed return origins for this mode." } } } } }, "description": "The request is not valid.\n\n- `invalid`: A field is not valid. Each bad field is a key holding a list of messages; there is no `detail`.\n- `url_invalid`: `return_url` or `cancel_url` is not https (http only for localhost), or has user info or a fragment.\n- `origin_not_allowed`: The URL's origin is not on the channel's allowed return origins for this mode." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_authenticated": { "summary": "The access token is missing, expired or unknown, or its key was revoked.", "value": { "type": "/exceptions/not_authenticated/", "title": "Authentication credentials were not provided.", "status": 401, "detail": "Authentication credentials were not provided." } } } } }, "description": "The access token is missing, not valid or expired.\n\n- `not_authenticated`: The access token is missing, expired or unknown, or its key was revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "permission_denied": { "summary": "The token is not a channel key's client-credentials token.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "You do not have permission to perform this action." } }, "secret_key_used_in_browser": { "summary": "The call came from a web browser (it carried Sec-Fetch-Site).", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The call came from a web browser (it carried Sec-Fetch-Site).", "code": "secret_key_used_in_browser" } }, "key_revoked_browser_use": { "summary": "The key was used from a browser, and the channel revokes keys used that way.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key was used from a browser, and the channel revokes keys used that way.", "code": "key_revoked_browser_use" } }, "account_unavailable": { "summary": "The merchant account is suspended, closed or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The merchant account is suspended, closed or deleted.", "code": "account_unavailable" } }, "channel_not_active": { "summary": "The sales channel is deleted or turned off.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The sales channel is deleted or turned off.", "code": "channel_not_active" } }, "store_not_available": { "summary": "The channel's store is missing or deleted.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The channel's store is missing or deleted.", "code": "store_not_available" } }, "feature_not_enabled": { "summary": "An account feature this call needs is off. The body's `features` lists them.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "An account feature this call needs is off. The body's `features` lists them.", "code": "feature_not_enabled", "features": [ "external_payments" ] } }, "capability_not_granted": { "summary": "The key lacks the capability: `payments` or `subscriptions`.", "value": { "type": "/exceptions/permission_denied/", "title": "You do not have permission to perform this action.", "status": 403, "detail": "The key lacks the capability: `payments` or `subscriptions`.", "code": "capability_not_granted" } } } } }, "description": "This key may not do this (capability, mode, feature or account state).\n\n- `permission_denied`: The token is not a channel key's client-credentials token.\n- `secret_key_used_in_browser`: The call came from a web browser (it carried Sec-Fetch-Site).\n- `key_revoked_browser_use`: The key was used from a browser, and the channel revokes keys used that way.\n- `account_unavailable`: The merchant account is suspended, closed or deleted.\n- `channel_not_active`: The sales channel is deleted or turned off.\n- `store_not_available`: The channel's store is missing or deleted.\n- `feature_not_enabled`: An account feature this call needs is off. The body's `features` lists them.\n- `capability_not_granted`: The key lacks the capability: `payments` or `subscriptions`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "No object with this uid for this key's channel and mode.", "value": { "type": "/exceptions/not_found/", "title": "Not found.", "status": 404, "detail": "Not found." } } } } }, "description": "Not found for this key.\n\n- `not_found`: No object with this uid for this key's channel and mode." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscription_invalid": { "summary": "The subscription is canceled or expired, so this change is not possible.", "value": { "type": "subscription_invalid", "title": "Subscription request refused.", "status": 409, "detail": "The subscription is canceled or expired, so this change is not possible." } } } } }, "description": "Refused in the current state. `type` holds the reason code.\n\n- `subscription_invalid`: The subscription is canceled or expired, so this change is not possible." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unavailable": { "summary": "The gateway refused or could not be reached, and nothing was charged.", "value": { "type": "gateway_unavailable", "title": "Subscription request refused.", "status": 502, "detail": "The gateway refused or could not be reached, and nothing was charged." } } } } }, "description": "The payment gateway did not answer as expected.\n\n- `gateway_unavailable`: The gateway refused or could not be reached, and nothing was charged." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "gateway_unconfigured": { "summary": "Hashry's live gateway is not configured.", "value": { "type": "gateway_unconfigured", "title": "Subscription request refused.", "status": 503, "detail": "Hashry's live gateway is not configured." } } } } }, "description": "The payment gateway is not available. Try again later.\n\n- `gateway_unconfigured`: Hashry's live gateway is not configured." } } } }, "/v1/public/payment-intents/{uid}/status": { "get": { "operationId": "payment_intent_status_retrieve", "description": "No key. The status token is the only credential. Browsers on the channel's allowed embed or return origins may read the answer.", "summary": "Read a payment's status from a browser", "parameters": [ { "in": "header", "name": "X-Hashry-Status-Token", "schema": { "type": "string" }, "description": "The `status_token` from create, retry or replay.", "required": true }, { "in": "path", "name": "uid", "schema": { "type": "string" }, "description": "The object's public uid.", "required": true } ], "tags": [ "Public" ], "security": [ {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentStatus" }, "examples": { "paid": { "summary": "Paid (for display only)", "value": { "status": "succeeded", "amount": "2500.00", "currency": "JMD", "updated_at": "2026-10-14T10:03:12Z" } } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } }, "description": "Unknown uid, or a wrong or expired token. The body does not say which." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "throttled": { "summary": "Too many requests for this key or account.", "value": { "type": "/exceptions/throttled/", "title": "Request was throttled.", "status": 429, "detail": "Request was throttled. Expected available in 30 seconds." } } } } }, "description": "Too many requests. Wait and try again.\n\n- `throttled`: Too many requests for this key or account." } } } } }, "components": { "schemas": { "ActivationActionEnum": { "enum": [ "contact_support" ], "type": "string", "description": "* `contact_support` - contact_support" }, "AttemptStatusEnum": { "enum": [ "pending", "creating", "redirect_issued", "succeeded", "failed", "expired", "canceled", "payment_review" ], "type": "string", "description": "* `pending` - pending\n* `creating` - creating\n* `redirect_issued` - redirect_issued\n* `succeeded` - succeeded\n* `failed` - failed\n* `expired` - expired\n* `canceled` - canceled\n* `payment_review` - payment_review" }, "BillingHoldEnum": { "enum": [ "hashry_configuration" ], "type": "string", "description": "* `hashry_configuration` - hashry_configuration" }, "BillingIntervalUnitEnum": { "enum": [ "day", "week", "month", "year" ], "type": "string", "description": "* `day` - day\n* `week` - week\n* `month` - month\n* `year` - year" }, "CardUpdateSession": { "type": "object", "properties": { "subscription_uid": { "type": "string" }, "update_url": { "type": [ "string", "null" ], "format": "uri", "description": "Send the customer here to replace the card." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/CardUpdateSessionStatusEnum" } }, "required": [ "expires_at", "status", "subscription_uid", "update_url" ] }, "CardUpdateSessionCreateRequest": { "type": "object", "description": "Request body for `update-card-session`. Both URLs must be on the\nchannel's allowed return origins.", "properties": { "return_url": { "type": "string", "default": "", "maxLength": 255 }, "cancel_url": { "type": "string", "default": "", "maxLength": 255 }, "reason": { "type": [ "string", "null" ], "maxLength": 64 } } }, "CardUpdateSessionStatusEnum": { "enum": [ "created", "open", "completed", "failed", "expired" ], "type": "string", "description": "* `created` - created\n* `open` - open\n* `completed` - completed\n* `failed` - failed\n* `expired` - expired" }, "ChannelKindEnum": { "enum": [ "admin_portal", "pos_terminal", "quick_store", "custom_store", "mobile_app", "social_instagram", "social_facebook", "social_tiktok", "marketplace_amazon", "payment_integration" ], "type": "string", "description": "* `admin_portal` - admin_portal\n* `pos_terminal` - pos_terminal\n* `quick_store` - quick_store\n* `custom_store` - custom_store\n* `mobile_app` - mobile_app\n* `social_instagram` - social_instagram\n* `social_facebook` - social_facebook\n* `social_tiktok` - social_tiktok\n* `marketplace_amazon` - marketplace_amazon\n* `payment_integration` - payment_integration" }, "ChannelSelf": { "type": "object", "description": "The channel, store and mode behind the calling key.", "properties": { "channel": { "$ref": "#/components/schemas/ChannelSelfChannel" }, "store": { "$ref": "#/components/schemas/ChannelSelfStore" }, "mode": { "$ref": "#/components/schemas/ModeEnum" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "The calling key's grant, expanded, sorted. Payment Integration keys can hold `payments` and `subscriptions`." } }, "required": [ "capabilities", "channel", "mode", "store" ] }, "ChannelSelfChannel": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ChannelKindEnum" } }, "required": [ "kind", "name", "uid" ] }, "ChannelSelfStore": { "type": "object", "properties": { "uid": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "base_currency": { "type": [ "string", "null" ] } }, "required": [ "base_currency", "name", "uid" ] }, "ClientCredentialsRequest": { "type": "object", "description": "A JSON body. Form-encoded bodies are refused.", "properties": { "grant_type": { "$ref": "#/components/schemas/GrantTypeEnum" }, "client_id": { "type": "string", "minLength": 1, "description": "The channel key's client id." }, "client_secret": { "type": "string", "minLength": 1, "description": "The channel key's secret. Server side only." } }, "required": [ "client_id", "client_secret", "grant_type" ] }, "DeliveryMethodEnum": { "enum": [ "redirect", "payment_link" ], "type": "string", "description": "* `redirect` - redirect\n* `payment_link` - payment_link" }, "EnrollmentTerminalReasonEnum": { "enum": [ "declined", "abandoned" ], "type": "string", "description": "* `declined` - declined\n* `abandoned` - abandoned" }, "ErrorDetail": { "type": "object", "description": "A short error body that is not a problem body.", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } }, "required": [ "detail" ] }, "ForgetCustomerRequest": { "type": "object", "properties": { "external_customer_reference": { "type": "string", "minLength": 1, "description": "Your id for the customer, from your own signed-in session." } }, "required": [ "external_customer_reference" ] }, "ForgetCustomerResult": { "type": "object", "properties": { "external_customer_reference": { "type": "string" }, "customer_found": { "type": "boolean" }, "customer_forgotten": { "type": "boolean" }, "cards_revoked": { "type": "integer" }, "cards_pending": { "type": "integer", "description": "Cards recorded as removed that the gateway has not confirmed yet." } }, "required": [ "cards_pending", "cards_revoked", "customer_forgotten", "customer_found", "external_customer_reference" ] }, "GrantTypeEnum": { "enum": [ "client_credentials" ], "type": "string", "description": "* `client_credentials` - client_credentials" }, "IntentKindEnum": { "enum": [ "payment", "subscription_enrollment" ], "type": "string", "description": "* `payment` - payment\n* `subscription_enrollment` - subscription_enrollment" }, "IntentStatusEnum": { "enum": [ "awaiting_customer", "processing", "redirect_issued", "requires_payment_method", "succeeded", "expired", "canceled", "payment_review" ], "type": "string", "description": "* `awaiting_customer` - awaiting_customer\n* `processing` - processing\n* `redirect_issued` - redirect_issued\n* `requires_payment_method` - requires_payment_method\n* `succeeded` - succeeded\n* `expired` - expired\n* `canceled` - canceled\n* `payment_review` - payment_review" }, "ModeEnum": { "enum": [ "live", "test" ], "type": "string", "description": "* `live` - live\n* `test` - test" }, "NullEnum": { "type": "null" }, "OAuthToken": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "description": "Seconds until the token expires." }, "token_type": { "$ref": "#/components/schemas/TokenTypeEnum" }, "scope": { "type": "string" } }, "required": [ "access_token", "expires_in", "scope", "token_type" ] }, "PaginatedPaymentMethodList": { "type": "object", "required": [ "count", "from", "to", "state", "current", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "All matching rows." }, "from": { "type": "integer", "description": "1-based index of the first row on this page." }, "to": { "type": "integer", "description": "1-based index of the last row on this page." }, "state": { "type": "object", "description": "The query parameters of this request.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "current": { "type": "string", "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "previous": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "PayerRequest": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 120 }, "last_name": { "type": "string", "maxLength": 120 }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "string", "maxLength": 0 } ] }, "phone": { "type": "string", "maxLength": 40 } } }, "PaymentAttempt": { "type": "object", "properties": { "uid": { "type": "string" }, "attempt_number": { "type": "integer" }, "status": { "$ref": "#/components/schemas/AttemptStatusEnum" }, "presentation": { "$ref": "#/components/schemas/PresentationEnum" }, "redirect_url": { "type": [ "string", "null" ], "format": "uri", "description": "The pay page, while it can still take a card. Otherwise null." }, "gateway_detail": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "attempt_number", "date_created", "expires_at", "gateway_detail", "presentation", "redirect_url", "status", "uid" ] }, "PaymentAttemptCreateRequest": { "type": "object", "description": "Request body for a retry. Amount, payer and URLs are fixed on the intent.", "properties": { "presentation": { "allOf": [ { "$ref": "#/components/schemas/PresentationEnum" } ], "default": "redirect" }, "embed_origin": { "type": [ "string", "null" ], "maxLength": 255 } } }, "PaymentEvent": { "type": "object", "description": "A payment changed state.", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "event_type": { "enum": [ "payment.succeeded", "payment.failed", "payment.expired", "payment.review_required", "payment.canceled" ], "type": "string", "description": "* `payment.succeeded` - payment.succeeded\n* `payment.failed` - payment.failed\n* `payment.expired` - payment.expired\n* `payment.review_required` - payment.review_required\n* `payment.canceled` - payment.canceled" }, "payment_intent_uid": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "enum": [ "awaiting_customer", "processing", "redirect_issued", "requires_payment_method", "succeeded", "expired", "canceled", "payment_review" ], "type": "string", "description": "* `awaiting_customer` - awaiting_customer\n* `processing` - processing\n* `redirect_issued` - redirect_issued\n* `requires_payment_method` - requires_payment_method\n* `succeeded` - succeeded\n* `expired` - expired\n* `canceled` - canceled\n* `payment_review` - payment_review" }, "delivery_method": { "enum": [ "redirect", "payment_link" ], "type": "string", "description": "* `redirect` - redirect\n* `payment_link` - payment_link" }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "customer_total": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "Absent on a success that a Hashry review released." }, "currency": { "type": "string" }, "external_customer_reference": { "type": "string", "description": "Only on payments created with a customer reference." }, "payment_method": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentCard" }, { "type": "null" } ], "description": "Only on payments created with a customer reference. The card saved or used." }, "payment_uid": { "type": "string", "description": "Only on a success that a Hashry review released." }, "resolved_from_review": { "type": "boolean", "description": "True on a success that a Hashry review released." } }, "required": [ "amount", "currency", "delivery_method", "event_id", "event_type", "external_reference", "payment_intent_uid", "status" ] }, "PaymentIntent": { "type": "object", "description": "A payment intent.\n\n`redirect_url`, `embed_url`, `embed_expires_at`,\n`transaction_uid`, `status_token`, `status_token_expires_at` and\n`status_url` come only from create, retry and an idempotent replay. Reads never\nreturn them.", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntentStatusEnum" }, "intent_kind": { "$ref": "#/components/schemas/IntentKindEnum" }, "delivery_method": { "$ref": "#/components/schemas/DeliveryMethodEnum" }, "link_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Payment links only. Otherwise null." }, "link_revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Payment links only. Otherwise null." }, "subscription_activation": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "external_reference": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_customer_uid": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "allow_save_card": { "type": "boolean" }, "offer_saved_cards": { "type": "boolean" }, "retry_after_decline": { "type": "boolean", "description": "True when the embedded card form takes another card after a decline. The payment then stays open; the frame posts `hashry.checkout.declined`." }, "description": { "type": [ "string", "null" ] }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "customer_total": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "What the payer is charged." }, "currency": { "type": "string" }, "mode": { "$ref": "#/components/schemas/ModeEnum" }, "amount_refunded": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "Sum of the refunds that succeeded." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRefund" }, "description": "Newest first, at most 20." }, "attention_required": { "type": "boolean", "description": "True while the payment is in review. Hashry staff resolve it." }, "retry_until": { "type": "string", "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAttempt" }, "description": "Newest first, at most 10." }, "captures": { "type": "array", "maxItems": 0, "items": {}, "description": "Staff only. Always an empty list on the partner API.", "readOnly": true }, "application": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "store": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "review_reason": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "payer": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "payment_method": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentCard" }, { "type": "null" } ], "description": "The saved card linked to this payment. Null until a capture links one." }, "payment_url": { "type": "null", "description": "Always null here. Payment links carry it.", "readOnly": true }, "redirect_url": { "type": "string", "format": "uri", "description": "The pay page. Send the payer here." }, "embed_url": { "type": "string", "format": "uri", "description": "Embedded presentation only: the card form URL for the frame. A bearer credential." }, "embed_expires_at": { "type": "string", "format": "date-time" }, "transaction_uid": { "type": "string", "description": "Embedded presentation only. Correlates the frame's messages." }, "status_token": { "type": "string", "description": "Browser-safe token for `GET /v1/public/payment-intents/{uid}/status`." }, "status_token_expires_at": { "type": "string", "format": "date-time" }, "status_url": { "type": "string", "format": "uri", "description": "Where the browser reads the status with `status_token`: this payment's `GET /v1/public/payment-intents/{uid}/status` on this API." } }, "required": [ "allow_save_card", "amount", "amount_refunded", "application", "attempts", "attention_required", "captures", "currency", "customer_total", "date_created", "delivery_method", "description", "external_customer_reference", "external_customer_uid", "external_reference", "fee", "intent_kind", "link_expires_at", "link_revoked_at", "mode", "offer_saved_cards", "payer", "payment_method", "payment_url", "refunds", "retry_after_decline", "retry_until", "review_reason", "status", "store", "subscription_activation", "uid" ] }, "PaymentIntentCard": { "type": "object", "description": "The saved card a payment used or saved. Masked; never a token.", "properties": { "uid": { "type": "string" }, "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] }, "card_exp_month": { "type": [ "integer", "null" ] }, "card_exp_year": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/PaymentMethodStatusEnum" }, "saved": { "type": "boolean", "description": "True when the customer saved the card on this payment." }, "used_saved_card": { "type": "boolean", "description": "True when the customer paid with a card saved before." } }, "required": [ "card_brand", "card_exp_month", "card_exp_year", "card_last4", "saved", "status", "uid", "used_saved_card" ] }, "PaymentIntentCreateRequest": { "type": "object", "description": "Request body for `POST /v1/channel/payment-intents`.", "properties": { "store_uid": { "type": [ "string", "null" ], "maxLength": 64 }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,15}(?:\\.\\d{0,4})?$" }, "currency": { "type": "string", "maxLength": 3 }, "description": { "type": "string", "maxLength": 255 }, "external_reference": { "type": "string", "maxLength": 120 }, "payer": { "$ref": "#/components/schemas/PayerRequest" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 255 }, "cancel_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 255 }, "presentation": { "allOf": [ { "$ref": "#/components/schemas/PresentationEnum" } ], "default": "redirect" }, "embed_origin": { "type": [ "string", "null" ], "maxLength": 255 }, "external_customer_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "allow_save_card": { "type": "boolean", "default": false }, "offer_saved_cards": { "type": "boolean", "default": false }, "retry_after_decline": { "type": "boolean", "default": false } }, "required": [ "amount", "cancel_url", "return_url" ] }, "PaymentIntentList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntent" }, "description": "Newest first, at most 50." } }, "required": [ "results" ] }, "PaymentIntentStatus": { "type": "object", "description": "What the public, browser-safe status endpoint returns.", "properties": { "status": { "$ref": "#/components/schemas/IntentStatusEnum" }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "currency": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "amount", "currency", "status", "updated_at" ] }, "PaymentLink": { "type": "object", "description": "A payment link: a payment intent the payer opens from a shared URL.", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntentStatusEnum" }, "intent_kind": { "$ref": "#/components/schemas/IntentKindEnum" }, "delivery_method": { "$ref": "#/components/schemas/DeliveryMethodEnum" }, "link_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Payment links only. Otherwise null." }, "link_revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Payment links only. Otherwise null." }, "subscription_activation": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "external_reference": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_customer_uid": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "allow_save_card": { "type": "boolean" }, "offer_saved_cards": { "type": "boolean" }, "retry_after_decline": { "type": "boolean", "description": "True when the embedded card form takes another card after a decline. The payment then stays open; the frame posts `hashry.checkout.declined`." }, "description": { "type": [ "string", "null" ] }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "customer_total": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "What the payer is charged." }, "currency": { "type": "string" }, "mode": { "$ref": "#/components/schemas/ModeEnum" }, "amount_refunded": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "Sum of the refunds that succeeded." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRefund" }, "description": "Newest first, at most 20." }, "attention_required": { "type": "boolean", "description": "True while the payment is in review. Hashry staff resolve it." }, "retry_until": { "type": "string", "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAttempt" }, "description": "Newest first, at most 10." }, "captures": { "type": "array", "maxItems": 0, "items": {}, "description": "Staff only. Always an empty list on the partner API.", "readOnly": true }, "application": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "store": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "review_reason": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "payer": { "type": "null", "description": "Staff only. Always null on the partner API.", "readOnly": true }, "payment_method": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentCard" }, { "type": "null" } ], "description": "The saved card linked to this payment. Null until a capture links one." }, "payment_url": { "type": [ "string", "null" ], "format": "uri", "description": "The shareable link. Null when it can no longer be built." } }, "required": [ "allow_save_card", "amount", "amount_refunded", "application", "attempts", "attention_required", "captures", "currency", "customer_total", "date_created", "delivery_method", "description", "external_customer_reference", "external_customer_uid", "external_reference", "fee", "intent_kind", "link_expires_at", "link_revoked_at", "mode", "offer_saved_cards", "payer", "payment_method", "payment_url", "refunds", "retry_after_decline", "retry_until", "review_reason", "status", "store", "subscription_activation", "uid" ] }, "PaymentLinkCreateRequest": { "type": "object", "description": "Request body for `POST /v1/channel/payment-links`.\n\nA link never carries a customer reference or saved-card flags, and it\nalways opens the full payment page.", "properties": { "store_uid": { "type": [ "string", "null" ], "maxLength": 64 }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,15}(?:\\.\\d{0,4})?$" }, "currency": { "type": "string", "maxLength": 3 }, "description": { "type": "string", "maxLength": 255 }, "external_reference": { "type": "string", "maxLength": 120 }, "payer": { "$ref": "#/components/schemas/PayerRequest" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 255 }, "cancel_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 255 }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "amount", "cancel_url", "return_url" ] }, "PaymentLinkList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" }, "description": "Newest first, at most 50." } }, "required": [ "results" ] }, "PaymentMethod": { "type": "object", "description": "A card the customer saved through this channel. Masked; never a token.", "properties": { "uid": { "type": "string" }, "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] }, "card_exp_month": { "type": [ "integer", "null" ] }, "card_exp_year": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/PaymentMethodStatusEnum" }, "revocation_pending": { "type": "boolean", "description": "A removal was asked for and the gateway has not confirmed it. The card is already unusable." }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "card_brand", "card_exp_month", "card_exp_year", "card_last4", "date_created", "revocation_pending", "status", "uid" ] }, "PaymentMethodStatusEnum": { "enum": [ "active", "revoked", "expired", "token_refresh_required" ], "type": "string", "description": "* `active` - active\n* `revoked` - revoked\n* `expired` - expired\n* `token_refresh_required` - token_refresh_required" }, "PaymentRefund": { "type": "object", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/RefundStatusEnum" }, "principal_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The part of the payment amount returned." }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The part of the fee returned." }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The total returned to the card." }, "currency": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "date_created": { "type": "string", "format": "date-time" }, "processed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "amount", "currency", "date_created", "fee_amount", "principal_amount", "processed_at", "reason", "status", "uid" ] }, "PaymentRefundedEvent": { "type": "object", "description": "A refund of the payment succeeded. Refunds are made in the Hashry admin.", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "event_type": { "enum": [ "payment.refunded" ], "type": "string", "description": "* `payment.refunded` - payment.refunded" }, "payment_intent_uid": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "refund": { "$ref": "#/components/schemas/WebhookRefund" } }, "required": [ "event_id", "event_type", "external_reference", "payment_intent_uid", "refund" ] }, "PaymentTestEvent": { "type": "object", "description": "Sent from the Hashry admin to check your endpoint. No money moved.", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "event_type": { "enum": [ "payment.test" ], "type": "string", "description": "* `payment.test` - payment.test" }, "message": { "type": "string" } }, "required": [ "event_id", "event_type", "message" ] }, "PresentationEnum": { "enum": [ "redirect", "embedded" ], "type": "string", "description": "* `redirect` - redirect\n* `embedded` - embedded" }, "Problem": { "type": "object", "description": "An RFC 7807 problem body.\n\n`type` is a short reason code (for example `currency_mismatch`) or a\n`/exceptions//` path. A validation error\nhas no `detail`: each bad field is a key that holds a list of\nmessages. Other keys can appear, for example `code` on a 403 or\n`payment_intent_uid` when the gateway call failed after the payment\nwas saved.", "properties": { "type": { "type": "string", "description": "The reason code, or `/exceptions//`. The codes are listed in the API description." }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "The reason code when the key may not make the call (403)." }, "features": { "type": "array", "items": { "type": "string" }, "description": "With `feature_not_enabled`: the account features that are off." }, "payment_intent_uid": { "type": "string", "description": "The payment, when the gateway call failed after it was saved." }, "subscription_intent_uid": { "type": "string", "description": "The enrollment, when the gateway call failed after it was saved." } }, "required": [ "status", "title", "type" ], "additionalProperties": true }, "RefundStatusEnum": { "enum": [ "pending", "processing", "succeeded", "failed", "outcome_unknown", "review_required" ], "type": "string", "description": "* `pending` - pending\n* `processing` - processing\n* `succeeded` - succeeded\n* `failed` - failed\n* `outcome_unknown` - outcome_unknown\n* `review_required` - review_required" }, "Subscription": { "type": "object", "description": "A subscription. `current_period_*` is the last PAID period.", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" }, "external_subscription_reference": { "type": "string" }, "external_customer_reference": { "type": [ "string", "null" ] }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "plan_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "recurring_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "setup_fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "billing_interval_unit": { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, "billing_interval_count": { "type": "integer" }, "trial_mode": { "$ref": "#/components/schemas/TrialModeEnum" }, "trial_interval_unit": { "oneOf": [ { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "trial_interval_count": { "type": [ "integer", "null" ] }, "trial_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "term_mode": { "$ref": "#/components/schemas/TermModeEnum" }, "term_cycle_count": { "type": [ "integer", "null" ] }, "cycles_completed": { "type": "integer" }, "cycles_waived": { "type": "integer" }, "cancel_at_period_end": { "type": "boolean" }, "cancel_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "effective_end_at": { "type": [ "string", "null" ], "format": "date-time" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "expired_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_end_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_charge_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "terms_fingerprint": { "type": [ "string", "null" ] }, "accepted_terms_at": { "type": [ "string", "null" ], "format": "date-time" }, "billing_hold": { "description": "Set while Hashry's own configuration stops billing. Otherwise null.\n\n* `hashry_configuration` - hashry_configuration", "oneOf": [ { "$ref": "#/components/schemas/BillingHoldEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "card": { "oneOf": [ { "$ref": "#/components/schemas/SubscriptionCard" }, { "type": "null" } ] } }, "required": [ "accepted_terms_at", "billing_hold", "billing_interval_count", "billing_interval_unit", "cancel_at_period_end", "cancel_requested_at", "canceled_at", "card", "currency", "current_period_end_at", "current_period_start_at", "cycles_completed", "cycles_waived", "description", "effective_end_at", "enrollment_intent_uid", "expired_at", "external_customer_reference", "external_subscription_reference", "next_charge_at", "next_retry_at", "plan_name", "recurring_amount", "setup_fee_amount", "started_at", "status", "term_cycle_count", "term_mode", "terms_fingerprint", "trial_amount", "trial_interval_count", "trial_interval_unit", "trial_mode", "uid" ] }, "SubscriptionActivatedEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.activated" ], "type": "string", "description": "* `subscription.activated` - subscription.activated" }, "current_period_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_end_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_charge_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "current_period_end_at", "current_period_start_at", "enrollment_intent_uid", "event_id", "event_type", "external_customer_reference", "external_subscription_reference", "next_charge_at", "occurred_at", "schema_version", "status", "subscription_uid" ] }, "SubscriptionActivationStatusEnum": { "enum": [ "not_applicable", "pending", "activated", "action_required", "abandoned" ], "type": "string", "description": "* `not_applicable` - not_applicable\n* `pending` - pending\n* `activated` - activated\n* `action_required` - action_required\n* `abandoned` - abandoned" }, "SubscriptionCanceledEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.canceled" ], "type": "string", "description": "* `subscription.canceled` - subscription.canceled" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "effective_end_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "canceled_at", "effective_end_at", "enrollment_intent_uid", "event_id", "event_type", "external_customer_reference", "external_subscription_reference", "occurred_at", "schema_version", "status", "subscription_uid" ] }, "SubscriptionCancellationScheduledEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.cancellation_scheduled" ], "type": "string", "description": "* `subscription.cancellation_scheduled` - subscription.cancellation_scheduled" }, "effective_end_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "effective_end_at", "enrollment_intent_uid", "event_id", "event_type", "external_customer_reference", "external_subscription_reference", "occurred_at", "schema_version", "status", "subscription_uid" ] }, "SubscriptionCard": { "type": "object", "properties": { "brand": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "exp_month": { "type": [ "integer", "null" ] }, "exp_year": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/PaymentMethodStatusEnum" } }, "required": [ "brand", "exp_month", "exp_year", "last4", "status" ] }, "SubscriptionCharge": { "type": "object", "properties": { "uid": { "type": "string" }, "cycle_uid": { "type": [ "string", "null" ] }, "attempt_number": { "type": "integer" }, "status": { "$ref": "#/components/schemas/SubscriptionChargeStatusEnum" }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_category": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean" }, "refund_summary": { "$ref": "#/components/schemas/SubscriptionChargeRefundSummary" } }, "required": [ "amount", "attempt_number", "completed_at", "currency", "cycle_uid", "due_at", "failure_category", "period_end", "period_start", "refund_summary", "retryable", "status", "uid" ] }, "SubscriptionChargeEvent": { "type": "object", "description": "A renewal charge settled. `past_due` and `payment_method_update_required`\nfollow a failed charge and say what happens next.", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.charge_succeeded", "subscription.charge_failed", "subscription.past_due", "subscription.payment_method_update_required" ], "type": "string", "description": "* `subscription.charge_succeeded` - subscription.charge_succeeded\n* `subscription.charge_failed` - subscription.charge_failed\n* `subscription.past_due` - subscription.past_due\n* `subscription.payment_method_update_required` - subscription.payment_method_update_required" }, "charge_uid": { "type": "string" }, "cycle_uid": { "type": [ "string", "null" ] }, "attempt_number": { "type": "integer" }, "charge_status": { "enum": [ "pending", "success", "declined", "failed", "outcome_unknown", "review_required" ], "type": "string", "description": "* `pending` - pending\n* `success` - success\n* `declined` - declined\n* `failed` - failed\n* `outcome_unknown` - outcome_unknown\n* `review_required` - review_required" }, "amount": { "type": [ "string", "null" ], "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "failure_category": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "retry_cycle_uid": { "type": [ "string", "null" ], "description": "On past_due and payment_method_update_required only." }, "next_action": { "enum": [ "await_retry", "update_card" ], "type": "string", "description": "On past_due (await_retry) and payment_method_update_required (update_card) only.\n\n* `await_retry` - await_retry\n* `update_card` - update_card" } }, "required": [ "amount", "attempt_number", "charge_status", "charge_uid", "currency", "cycle_uid", "due_at", "enrollment_intent_uid", "event_id", "event_type", "external_customer_reference", "external_subscription_reference", "failure_category", "next_retry_at", "occurred_at", "period_end", "period_start", "retryable", "schema_version", "status", "subscription_uid" ] }, "SubscriptionChargeList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionCharge" }, "description": "Newest first, at most 100." } }, "required": [ "results" ] }, "SubscriptionChargeRefundSummary": { "type": "object", "properties": { "amount_refunded": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "refund_count": { "type": "integer" } }, "required": [ "amount_refunded", "refund_count" ] }, "SubscriptionChargeStatusEnum": { "enum": [ "pending", "success", "declined", "failed", "outcome_unknown", "review_required" ], "type": "string", "description": "* `pending` - pending\n* `success` - success\n* `declined` - declined\n* `failed` - failed\n* `outcome_unknown` - outcome_unknown\n* `review_required` - review_required" }, "SubscriptionEnrollmentEvent": { "type": "object", "description": "The enrollment payment was declined, or the customer never paid.", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.enrollment_failed", "subscription.enrollment_expired" ], "type": "string", "description": "* `subscription.enrollment_failed` - subscription.enrollment_failed\n* `subscription.enrollment_expired` - subscription.enrollment_expired" }, "terminal_reason": { "enum": [ "declined", "abandoned" ], "type": "string", "description": "* `declined` - declined\n* `abandoned` - abandoned" } }, "required": [ "enrollment_intent_uid", "event_id", "event_type", "external_customer_reference", "external_subscription_reference", "occurred_at", "schema_version", "status", "subscription_uid", "terminal_reason" ] }, "SubscriptionExpiredEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Stable across every retry of this event. Your de-duplication key." }, "schema_version": { "type": "integer", "description": "1. A new version is a new field, never a changed one." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrollment_intent_uid": { "type": [ "string", "null" ] }, "subscription_uid": { "type": [ "string", "null" ] }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The subscription's status, or before activation the enrollment's activation status." }, "event_type": { "enum": [ "subscription.expired" ], "type": "string", "description": "* `subscription.expired` - subscription.expired" }, "expired_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enrollment_intent_uid", "event_id", "event_type", "expired_at", "external_customer_reference", "external_subscription_reference", "occurred_at", "schema_version", "status", "subscription_uid" ] }, "SubscriptionFirstPayment": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The amount due today, before the fee." }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "customer_total": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" } }, "required": [ "amount", "customer_total", "fee_amount" ] }, "SubscriptionIntent": { "type": "object", "description": "An enrollment: the first payment that starts a subscription.\n\n`redirect_url` comes only from create and an idempotent replay.", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntentStatusEnum" }, "intent_kind": { "$ref": "#/components/schemas/IntentKindEnum" }, "external_customer_reference": { "type": [ "string", "null" ] }, "external_subscription_reference": { "type": [ "string", "null" ] }, "amount_due_today": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "customer_total": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "currency": { "type": "string" }, "plan": { "$ref": "#/components/schemas/SubscriptionPlanTerms" }, "subscription_activation_status": { "$ref": "#/components/schemas/SubscriptionActivationStatusEnum" }, "activation_action": { "description": "What the partner must do when activation needs help. Otherwise null.\n\n* `contact_support` - contact_support", "oneOf": [ { "$ref": "#/components/schemas/ActivationActionEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "subscription_uid": { "type": [ "string", "null" ], "description": "Set once the subscription is active." }, "enrollment_terminal_reason": { "oneOf": [ { "$ref": "#/components/schemas/EnrollmentTerminalReasonEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "amount_refunded": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "retry_until": { "type": "string", "format": "date-time" }, "date_created": { "type": "string", "format": "date-time" }, "redirect_url": { "type": "string", "format": "uri", "description": "The pay page. Send the payer here." } }, "required": [ "activation_action", "amount_due_today", "amount_refunded", "currency", "customer_total", "date_created", "enrollment_terminal_reason", "external_customer_reference", "external_subscription_reference", "fee", "intent_kind", "plan", "retry_until", "status", "subscription_activation_status", "subscription_uid", "uid" ] }, "SubscriptionIntentCreateRequest": { "type": "object", "description": "Request body for `POST /v1/channel/subscription-intents`. Live keys only.", "properties": { "plan": { "$ref": "#/components/schemas/SubscriptionPlanRequest" }, "payer": { "$ref": "#/components/schemas/PayerRequest" }, "external_customer_reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "external_subscription_reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": "string", "maxLength": 3 }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 500 }, "cancel_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 500 } }, "required": [ "cancel_url", "external_customer_reference", "external_subscription_reference", "payer", "plan", "return_url" ] }, "SubscriptionIntentList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionIntent" }, "description": "Newest first, at most 50." } }, "required": [ "results" ] }, "SubscriptionList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" }, "description": "Newest first, at most 50." } }, "required": [ "results" ] }, "SubscriptionPlanRequest": { "type": "object", "description": "The partner-named plan. The amount due today is NOT here — it is\nderived server-side (E6).", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 350 }, "description": { "type": "string", "maxLength": 550 }, "recurring_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,15}(?:\\.\\d{0,4})?$" }, "setup_fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,15}(?:\\.\\d{0,4})?$" }, "billing_interval_unit": { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, "billing_interval_count": { "type": "integer", "maximum": 366, "minimum": 1 }, "trial_mode": { "$ref": "#/components/schemas/TrialModeEnum" }, "trial_interval_unit": { "oneOf": [ { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "trial_interval_count": { "type": [ "integer", "null" ], "maximum": 366, "minimum": 1 }, "trial_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,15}(?:\\.\\d{0,4})?$" }, "term_mode": { "$ref": "#/components/schemas/TermModeEnum" }, "term_cycle_count": { "type": [ "integer", "null" ], "maximum": 1000, "minimum": 1 } }, "required": [ "billing_interval_unit", "name", "recurring_amount" ] }, "SubscriptionPlanTerms": { "type": "object", "description": "The plan as the payer accepted it (the canonical consent terms).", "properties": { "plan_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "first_payment": { "$ref": "#/components/schemas/SubscriptionFirstPayment" }, "recurring_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "setup_fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "billing_interval_unit": { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, "billing_interval_count": { "type": "integer" }, "trial_mode": { "$ref": "#/components/schemas/TrialModeEnum" }, "trial_interval_unit": { "oneOf": [ { "$ref": "#/components/schemas/BillingIntervalUnitEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "trial_interval_count": { "type": [ "integer", "null" ] }, "trial_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "term_mode": { "$ref": "#/components/schemas/TermModeEnum" }, "term_cycle_count": { "type": [ "integer", "null" ] }, "cancellation_terms_version": { "type": "string" } }, "required": [ "billing_interval_count", "billing_interval_unit", "cancellation_terms_version", "currency", "description", "first_payment", "plan_name", "recurring_amount", "setup_fee_amount", "term_cycle_count", "term_mode", "trial_amount", "trial_interval_count", "trial_interval_unit", "trial_mode" ] }, "SubscriptionRetryResult": { "type": "object", "properties": { "subscription_uid": { "type": "string" }, "charge_created": { "type": "boolean", "description": "True when a charge was sent to the gateway, whatever its outcome." }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" } }, "required": [ "charge_created", "status", "subscription_uid" ] }, "SubscriptionStatusEnum": { "enum": [ "active", "past_due", "paused", "suspended", "payment_method_update_required", "canceled", "expired" ], "type": "string", "description": "* `active` - active\n* `past_due` - past_due\n* `paused` - paused\n* `suspended` - suspended\n* `payment_method_update_required` - payment_method_update_required\n* `canceled` - canceled\n* `expired` - expired" }, "TermModeEnum": { "enum": [ "evergreen", "fixed_cycles" ], "type": "string", "description": "* `evergreen` - evergreen\n* `fixed_cycles` - fixed_cycles" }, "TokenTypeEnum": { "enum": [ "Bearer" ], "type": "string", "description": "* `Bearer` - Bearer" }, "TrialModeEnum": { "enum": [ "none", "free", "paid" ], "type": "string", "description": "* `none` - none\n* `free` - free\n* `paid` - paid" }, "WebhookRefund": { "type": "object", "properties": { "uid": { "type": "string" }, "status": { "enum": [ "pending", "processing", "succeeded", "failed", "outcome_unknown", "review_required" ], "type": "string", "description": "* `pending` - pending\n* `processing` - processing\n* `succeeded` - succeeded\n* `failed` - failed\n* `outcome_unknown` - outcome_unknown\n* `review_required` - review_required" }, "principal_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The part of the payment amount returned." }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The part of the fee returned." }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$", "description": "The total returned to the card." }, "merchant_fee_credit_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,17}(?:\\.\\d{0,2})?$" }, "currency": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "gateway_refund_uid": { "type": [ "string", "null" ] }, "gateway_transaction_identifier": { "type": [ "string", "null" ] }, "response_message": { "type": [ "string", "null" ] }, "processed_at": { "type": [ "string", "null" ], "format": "date-time" }, "date_created": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "amount", "currency", "date_created", "fee_amount", "gateway_refund_uid", "gateway_transaction_identifier", "merchant_fee_credit_amount", "principal_amount", "processed_at", "reason", "response_message", "status", "uid" ] } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Send `Authorization: Bearer `. Partners get the token from `POST /auth/token` with the client credentials grant.", "flows": { "clientCredentials": { "tokenUrl": "/auth/token", "scopes": {} } } } } }, "webhooks": { "payment.succeeded": { "post": { "description": "A payment succeeded.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.succeeded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" }, "examples": { "payment.succeeded": { "summary": "A payment succeeded", "value": { "event_type": "payment.succeeded", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "status": "succeeded", "delivery_method": "redirect", "amount": "2500.00", "customer_total": "2575.00", "currency": "JMD", "event_id": "evt_00000000000000000000000c0ffee000" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.failed": { "post": { "description": "A payment needs a new attempt: every card the card form allowed was declined.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" }, "examples": { "payment.failed": { "summary": "A payment needs a new attempt: every card the card form allowed was declined", "value": { "event_type": "payment.failed", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "status": "requires_payment_method", "delivery_method": "redirect", "amount": "2500.00", "customer_total": "2575.00", "currency": "JMD", "event_id": "evt_00000000000000000000000c0ffee000" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.expired": { "post": { "description": "A payment passed its retry window. Nothing was charged.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.expired", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" }, "examples": { "payment.expired": { "summary": "A payment passed its retry window. Nothing was charged", "value": { "event_type": "payment.expired", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "status": "expired", "delivery_method": "redirect", "amount": "2500.00", "customer_total": "2575.00", "currency": "JMD", "event_id": "evt_00000000000000000000000c0ffee000" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.review_required": { "post": { "description": "Hashry staff are checking a payment.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.review_required", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" }, "examples": { "payment.review_required": { "summary": "Hashry staff are checking a payment", "value": { "event_type": "payment.review_required", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "status": "payment_review", "delivery_method": "redirect", "amount": "2500.00", "customer_total": "2575.00", "currency": "JMD", "event_id": "evt_00000000000000000000000c0ffee000" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.canceled": { "post": { "description": "A payment was canceled before a card was sent. Opt-in: the merchant turns it on.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.canceled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" }, "examples": { "payment.canceled": { "summary": "A payment was canceled before a card was sent. Opt-in: the merchant turns it on", "value": { "event_type": "payment.canceled", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "status": "canceled", "delivery_method": "redirect", "amount": "2500.00", "customer_total": "2575.00", "currency": "JMD", "event_id": "evt_00000000000000000000000c0ffee000" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.refunded": { "post": { "description": "A refund succeeded.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.refunded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRefundedEvent" }, "examples": { "payment.refunded": { "summary": "A refund succeeded", "value": { "event_type": "payment.refunded", "payment_intent_uid": "3kTMd9pQxV7bWzR2nLc8Fh", "external_reference": "order-1042", "refund": { "uid": "rfd_5Hq2mN4pX9kR", "status": "succeeded", "principal_amount": "1000.00", "fee_amount": "30.00", "amount": "1030.00", "merchant_fee_credit_amount": "0.00", "currency": "JMD", "reason": "Damaged item", "gateway_refund_uid": "rf_7d1e9b2c4a6f", "gateway_transaction_identifier": "81234567", "response_message": "Approved", "processed_at": "2026-10-16T09:12:00+00:00", "date_created": "2026-10-16T09:11:58+00:00" }, "event_id": "evt_00000000000000000000000c0ffee222" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "payment.test": { "post": { "description": "A test event from the Hashry admin.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "payment.test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTestEvent" }, "examples": { "payment.test": { "summary": "A test event from the Hashry admin", "value": { "event_type": "payment.test", "message": "This is a test event from Hashry. No money moved.", "event_id": "evt_00000000000000000000000c0ffee333" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.activated": { "post": { "description": "A subscription started.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.activated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionActivatedEvent" }, "examples": { "subscription.activated": { "summary": "A subscription started", "value": { "event_type": "subscription.activated", "schema_version": 1, "occurred_at": "2026-10-14T10:02:31+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "active", "current_period_start_at": "2026-10-14T10:02:31+00:00", "current_period_end_at": "2026-11-14T10:02:31+00:00", "next_charge_at": "2026-11-14T10:02:31+00:00", "event_id": "evt_00000000000000000000000c0ffee444" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.enrollment_failed": { "post": { "description": "The enrollment payment was declined.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.enrollment_failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEnrollmentEvent" }, "examples": { "subscription.enrollment_failed": { "summary": "The enrollment payment was declined", "value": { "event_type": "subscription.enrollment_failed", "schema_version": 1, "occurred_at": "2026-10-14T10:05:00+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": null, "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "abandoned", "terminal_reason": "declined", "event_id": "evt_00000000000000000000000c0ffee555" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.enrollment_expired": { "post": { "description": "The customer never paid the enrollment.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.enrollment_expired", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEnrollmentEvent" }, "examples": { "subscription.enrollment_expired": { "summary": "The customer never paid the enrollment", "value": { "event_type": "subscription.enrollment_expired", "schema_version": 1, "occurred_at": "2026-10-21T10:00:00+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": null, "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "abandoned", "terminal_reason": "abandoned", "event_id": "evt_00000000000000000000000c0ffee666" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.charge_succeeded": { "post": { "description": "A renewal charge succeeded.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.charge_succeeded", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChargeEvent" }, "examples": { "subscription.charge_succeeded": { "summary": "A renewal charge succeeded", "value": { "event_type": "subscription.charge_succeeded", "schema_version": 1, "occurred_at": "2026-11-14T10:02:40+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "active", "charge_uid": "chg_8Tq2mW7xR4kN", "cycle_uid": "cyc_2026_11", "attempt_number": 1, "charge_status": "success", "amount": "3090.00", "currency": "JMD", "due_at": "2026-11-14T10:02:31+00:00", "period_start": "2026-11-14T10:02:31+00:00", "period_end": "2026-12-14T10:02:31+00:00", "failure_category": null, "retryable": false, "next_retry_at": null, "event_id": "evt_00000000000000000000000c0ffee111" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.charge_failed": { "post": { "description": "A renewal charge failed.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.charge_failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChargeEvent" }, "examples": { "subscription.charge_failed": { "summary": "A renewal charge failed", "value": { "event_type": "subscription.charge_failed", "schema_version": 1, "occurred_at": "2026-11-14T10:02:40+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "past_due", "charge_uid": "chg_8Tq2mW7xR4kN", "cycle_uid": "cyc_2026_11", "attempt_number": 1, "charge_status": "declined", "amount": "3090.00", "currency": "JMD", "due_at": "2026-11-14T10:02:31+00:00", "period_start": "2026-11-14T10:02:31+00:00", "period_end": "2026-12-14T10:02:31+00:00", "failure_category": "insufficient_funds", "retryable": true, "next_retry_at": "2026-11-16T10:02:31+00:00", "event_id": "evt_00000000000000000000000c0ffee111" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.past_due": { "post": { "description": "Hashry will charge the card again.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.past_due", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChargeEvent" }, "examples": { "subscription.past_due": { "summary": "Hashry will charge the card again", "value": { "event_type": "subscription.past_due", "schema_version": 1, "occurred_at": "2026-11-14T10:02:40+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "past_due", "charge_uid": "chg_8Tq2mW7xR4kN", "cycle_uid": "cyc_2026_11", "attempt_number": 1, "charge_status": "declined", "amount": "3090.00", "currency": "JMD", "due_at": "2026-11-14T10:02:31+00:00", "period_start": "2026-11-14T10:02:31+00:00", "period_end": "2026-12-14T10:02:31+00:00", "failure_category": "insufficient_funds", "retryable": true, "next_retry_at": "2026-11-16T10:02:31+00:00", "retry_cycle_uid": "cyc_2026_11", "next_action": "await_retry", "event_id": "evt_00000000000000000000000c0ffee111" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.payment_method_update_required": { "post": { "description": "The customer must replace their card.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.payment_method_update_required", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChargeEvent" }, "examples": { "subscription.payment_method_update_required": { "summary": "The customer must replace their card", "value": { "event_type": "subscription.payment_method_update_required", "schema_version": 1, "occurred_at": "2026-11-14T10:02:40+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "payment_method_update_required", "charge_uid": "chg_8Tq2mW7xR4kN", "cycle_uid": "cyc_2026_11", "attempt_number": 1, "charge_status": "declined", "amount": "3090.00", "currency": "JMD", "due_at": "2026-11-14T10:02:31+00:00", "period_start": "2026-11-14T10:02:31+00:00", "period_end": "2026-12-14T10:02:31+00:00", "failure_category": "insufficient_funds", "retryable": true, "next_retry_at": "2026-11-16T10:02:31+00:00", "retry_cycle_uid": "cyc_2026_11", "next_action": "update_card", "event_id": "evt_00000000000000000000000c0ffee111" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.cancellation_scheduled": { "post": { "description": "The subscription ends at the end of the paid period.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.cancellation_scheduled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCancellationScheduledEvent" }, "examples": { "subscription.cancellation_scheduled": { "summary": "The subscription ends at the end of the paid period", "value": { "event_type": "subscription.cancellation_scheduled", "schema_version": 1, "occurred_at": "2026-10-20T09:00:00+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "active", "effective_end_at": "2026-11-14T10:02:31+00:00", "event_id": "evt_00000000000000000000000c0ffee777" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.canceled": { "post": { "description": "The subscription ended.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.canceled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCanceledEvent" }, "examples": { "subscription.canceled": { "summary": "The subscription ended", "value": { "event_type": "subscription.canceled", "schema_version": 1, "occurred_at": "2026-11-14T10:02:31+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "canceled", "canceled_at": "2026-11-14T10:02:31+00:00", "effective_end_at": "2026-11-14T10:02:31+00:00", "event_id": "evt_00000000000000000000000c0ffee888" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } }, "subscription.expired": { "post": { "description": "A fixed-term subscription finished.\n\nSigned like every Hashry webhook: verify `X-Hashry-Signature` over the raw body with your webhook secret before you trust it (the SDKs' `verifyWebhook` / `webhooks.verify`). Delivery is at least once and in any order: store `event_id` and apply each event once. The event is a cue: read the object from the API before you act on it. Answer 2xx; anything else is retried for up to a day.", "summary": "subscription.expired", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionExpiredEvent" }, "examples": { "subscription.expired": { "summary": "A fixed-term subscription finished", "value": { "event_type": "subscription.expired", "schema_version": 1, "occurred_at": "2027-10-14T10:02:31+00:00", "enrollment_intent_uid": "5nRw8KcT2mXq7LpV9hBz4F", "subscription_uid": "9cHm4TqW7xRn2KvB5pLz8D", "external_customer_reference": "cust-77", "external_subscription_reference": "sub-77-coffee", "status": "expired", "expired_at": "2027-10-14T10:02:31+00:00", "event_id": "evt_00000000000000000000000c0ffee999" } } } } }, "required": true }, "responses": { "200": { "description": "Received. Any 2xx works." } } } } } }