> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/en/api-reference/payment-intents.md).

# Payment intents

Create, retrieve, list, update, confirm and release payments.

A payment intent is one request for a buyer to pay. Read [Payments and statuses](/en/concepts/payments.md) and [Payment details](/en/concepts/payment-details.md) before you use these routes.

## Create a payment intent

> Prices the fees with your current fee schedule and fee bearer. \`items\` (what the payment is for) is required; the buyer, the order reference and, for physical goods, the shipping details may come now or by update, but must be there before the buyer pays (confirm answers 400 \`payment\_details\_missing\` otherwise). With an \`Idempotency-Key\`, the same key and body replay the stored response (same id and client\_secret); the same key with a different body is a 409. A suspended account gets a 400 \`merchant\_suspended\`.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"CreatePaymentIntentRequest":{"type":"object","properties":{"items":{"minItems":1,"maxItems":100,"description":"What the payment is for (required on create). Items describe the amount, they never set it: only `amount` is priced and charged; the difference is reported as `items_difference`. On update: replaces the whole list, and must be sent again when the currency changes.","type":"array","items":{"$ref":"#/components/schemas/PaymentItemInput"}},"shipping_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared discount, in minor units."},"goods_type":{"type":"string","enum":["physical","non_physical"],"default":"physical","description":"`non_physical`: digital goods and services, nothing ships. Only if your account may sell them."},"buyer":{"nullable":true,"description":"Required before the buyer pays (send it now or by update); null clears it on update.","type":"object","allOf":[{"$ref":"#/components/schemas/BuyerInput"}]},"order_reference":{"type":"string","nullable":true,"minLength":1,"maxLength":100,"description":"Your own number for the order (not unique). Required before the buyer pays; null clears it on update."},"shipping_details":{"nullable":true,"description":"Where the goods ship. Required before the buyer pays unless `goods_type` is `non_physical`; null clears it on update.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetailsInput"}]},"amount":{"type":"integer","minimum":1,"description":"Amount in minor units (cents), before any buyer-paid fee. The buyer is charged `amount_total` of the response."},"currency":{"type":"string","enum":["usd","eur"]},"description":{"type":"string","nullable":true,"maxLength":1000},"metadata":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Your own key/value data (at most 50 keys of up to 40 characters, string values up to 500 characters)."}},"required":["amount","currency"]},"PaymentItemInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals, at most 1,000,000."},"unit_amount":{"type":"integer","minimum":0,"maximum":99999999,"description":"Price of one, in minor units."}},"required":["name","quantity","unit_amount"]},"BuyerInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200}},"required":["name"]},"ShippingDetailsInput":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"The recipient."},"phone":{"type":"string","nullable":true,"maxLength":40},"address":{"$ref":"#/components/schemas/ShippingAddressInput"}},"required":["name","address"]},"ShippingAddressInput":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","nullable":true,"maxLength":200},"city":{"type":"string","nullable":true,"maxLength":200},"state":{"type":"string","nullable":true,"maxLength":200},"postal_code":{"type":"string","nullable":true,"maxLength":20},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","country"]},"PaymentIntent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_intent"]},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]},"currency":{"type":"string","enum":["usd","eur"]},"amount":{"type":"integer","description":"Amount before any buyer-paid fee, in minor units."},"fee_buyer":{"type":"integer","description":"Fees added to the total when the buyer bears them (processing_fee + bank_fee), else 0."},"amount_total":{"type":"integer","description":"Exactly what the buyer is charged and must be shown before paying (amount + fee_buyer)."},"processing_fee":{"type":"integer","description":"Processing fee of this payment, whoever bears it."},"bank_fee":{"type":"integer","description":"Bank fee of this payment, borne by the same party as the processing fee."},"fee_bearer":{"type":"string","enum":["merchant","buyer"]},"amount_refunded":{"type":"integer","description":"Refunded so far, refunds in flight included."},"amount_refundable":{"type":"integer","description":"What can still be refunded: amount_total less the processing and bank fees (fees are never refunded) less amount_refunded; 0 unless the payment succeeded."},"confirmation_attempts":{"type":"integer","description":"Payment attempts (confirms) sent so far. Each payment intent allows a limited number; once they are used, confirm answers `payment_intent_not_pending` and the buyer must restart checkout with a new payment intent."},"description":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"order_reference":{"type":"string","nullable":true,"description":"Your own number for the order; null until you send it. Required before the buyer pays."},"goods_type":{"type":"string","enum":["physical","non_physical"],"description":"`non_physical`: digital goods and services, nothing ships."},"buyer":{"nullable":true,"description":"Null until you send it. Required before the buyer pays.","type":"object","allOf":[{"$ref":"#/components/schemas/Buyer"}]},"shipping_details":{"nullable":true,"description":"Null until you send it. Required before the buyer pays, unless the goods are non_physical.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetails"}]},"items":{"description":"What the payment is for. Items describe the amount, they never set it.","type":"array","items":{"$ref":"#/components/schemas/PaymentItem"}},"shipping_amount":{"type":"integer","description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","description":"Declared discount, in minor units."},"items_difference":{"type":"integer","description":"`amount` − (the items' amounts + shipping_amount + tax_amount − discount_amount): 0 when your figures agree. Only reported: the payment is always charged for `amount`."},"billing_details":{"nullable":true,"description":"What the buyer entered with the card (the succeeded attempt's, else the latest attempt's); null before any attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/BillingDetails"}]},"client_secret":{"type":"string","description":"Only in the create response (and its idempotent replays). Pass it to the browser SDK."},"created":{"type":"integer","description":"Unix seconds."},"succeeded_at":{"type":"integer","nullable":true,"description":"Unix seconds."},"unlock_schedule":{"description":"The payment's unlock steps: when each part of what it brings you becomes available. Copied from your unlock schedule when the payment succeeds; empty before.","type":"array","items":{"$ref":"#/components/schemas/UnlockScheduleStep"}}},"required":["id","object","status","currency","amount","fee_buyer","amount_total","processing_fee","bank_fee","fee_bearer","amount_refunded","amount_refundable","confirmation_attempts","description","metadata","order_reference","goods_type","buyer","shipping_details","items","shipping_amount","tax_amount","discount_amount","items_difference","billing_details","created","succeeded_at","unlock_schedule"]},"Buyer":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ShippingDetails":{"type":"object","properties":{"name":{"type":"string","description":"The recipient."},"phone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/ShippingAddress"}},"required":["name","phone","address"]},"ShippingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"PaymentItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals."},"unit_amount":{"type":"integer","description":"Price of one, in minor units."},"amount":{"type":"integer","description":"This line in total: unit_amount × quantity, rounded half up once (minor units)."}},"required":["name","quantity","unit_amount","amount"]},"BillingDetails":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","description":"The name entered with the card."},"address":{"$ref":"#/components/schemas/BillingAddress"}},"required":["email","name","address"]},"BillingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"UnlockScheduleStep":{"type":"object","properties":{"step":{"type":"integer","description":"The step number, from 1, in order."},"days":{"type":"integer","nullable":true,"description":"Days after the payment succeeded. Null for payments that succeeded before unlock schedules existed."},"percent_bps":{"type":"integer","description":"Share of what the payment brings you, in basis points (8000 = 80 %)."},"available_at":{"type":"integer","description":"Unix seconds: when this step becomes available (a :00 or :30 mark, unless it was released early)."},"amount":{"type":"integer","description":"The step's part, in minor units, of what the payment brings you: amount_total less processing_fee and bank_fee (for fee_bearer buyer, that is the amount)."},"deducted":{"type":"integer","description":"What refunds (and their refund fees) took from this step."},"remaining":{"type":"integer","description":"amount − deducted."},"rescheduled":{"type":"boolean","description":"Whether its unlock time was changed by us."}},"required":["step","days","percent_bps","available_at","amount","deducted","remaining","rescheduled"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents":{"post":{"description":"Prices the fees with your current fee schedule and fee bearer. `items` (what the payment is for) is required; the buyer, the order reference and, for physical goods, the shipping details may come now or by update, but must be there before the buyer pays (confirm answers 400 `payment_details_missing` otherwise). With an `Idempotency-Key`, the same key and body replay the stored response (same id and client_secret); the same key with a different body is a 409. A suspended account gets a 400 `merchant_suspended`.","operationId":"createPaymentIntent","parameters":[{"name":"Idempotency-Key","required":false,"in":"header","description":"1 to 255 characters.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentIntentRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"invalid_request_error: `idempotency_key_reused`, or `payment_intent_updated` on confirm (the amount changed since the card form was loaded: load the form again, then confirm).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"api_error: `internal_error`, or `fee_plan_not_configured` when no fee schedule applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"api_error: `provider_error`, the payment could not be processed; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Create a payment intent","tags":["Payment intents"]}}}}
```

## GET /partner/v1/payment\_intents/{id}

> Retrieve a payment intent

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"PaymentIntent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_intent"]},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]},"currency":{"type":"string","enum":["usd","eur"]},"amount":{"type":"integer","description":"Amount before any buyer-paid fee, in minor units."},"fee_buyer":{"type":"integer","description":"Fees added to the total when the buyer bears them (processing_fee + bank_fee), else 0."},"amount_total":{"type":"integer","description":"Exactly what the buyer is charged and must be shown before paying (amount + fee_buyer)."},"processing_fee":{"type":"integer","description":"Processing fee of this payment, whoever bears it."},"bank_fee":{"type":"integer","description":"Bank fee of this payment, borne by the same party as the processing fee."},"fee_bearer":{"type":"string","enum":["merchant","buyer"]},"amount_refunded":{"type":"integer","description":"Refunded so far, refunds in flight included."},"amount_refundable":{"type":"integer","description":"What can still be refunded: amount_total less the processing and bank fees (fees are never refunded) less amount_refunded; 0 unless the payment succeeded."},"confirmation_attempts":{"type":"integer","description":"Payment attempts (confirms) sent so far. Each payment intent allows a limited number; once they are used, confirm answers `payment_intent_not_pending` and the buyer must restart checkout with a new payment intent."},"description":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"order_reference":{"type":"string","nullable":true,"description":"Your own number for the order; null until you send it. Required before the buyer pays."},"goods_type":{"type":"string","enum":["physical","non_physical"],"description":"`non_physical`: digital goods and services, nothing ships."},"buyer":{"nullable":true,"description":"Null until you send it. Required before the buyer pays.","type":"object","allOf":[{"$ref":"#/components/schemas/Buyer"}]},"shipping_details":{"nullable":true,"description":"Null until you send it. Required before the buyer pays, unless the goods are non_physical.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetails"}]},"items":{"description":"What the payment is for. Items describe the amount, they never set it.","type":"array","items":{"$ref":"#/components/schemas/PaymentItem"}},"shipping_amount":{"type":"integer","description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","description":"Declared discount, in minor units."},"items_difference":{"type":"integer","description":"`amount` − (the items' amounts + shipping_amount + tax_amount − discount_amount): 0 when your figures agree. Only reported: the payment is always charged for `amount`."},"billing_details":{"nullable":true,"description":"What the buyer entered with the card (the succeeded attempt's, else the latest attempt's); null before any attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/BillingDetails"}]},"client_secret":{"type":"string","description":"Only in the create response (and its idempotent replays). Pass it to the browser SDK."},"created":{"type":"integer","description":"Unix seconds."},"succeeded_at":{"type":"integer","nullable":true,"description":"Unix seconds."},"unlock_schedule":{"description":"The payment's unlock steps: when each part of what it brings you becomes available. Copied from your unlock schedule when the payment succeeds; empty before.","type":"array","items":{"$ref":"#/components/schemas/UnlockScheduleStep"}}},"required":["id","object","status","currency","amount","fee_buyer","amount_total","processing_fee","bank_fee","fee_bearer","amount_refunded","amount_refundable","confirmation_attempts","description","metadata","order_reference","goods_type","buyer","shipping_details","items","shipping_amount","tax_amount","discount_amount","items_difference","billing_details","created","succeeded_at","unlock_schedule"]},"Buyer":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ShippingDetails":{"type":"object","properties":{"name":{"type":"string","description":"The recipient."},"phone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/ShippingAddress"}},"required":["name","phone","address"]},"ShippingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"PaymentItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals."},"unit_amount":{"type":"integer","description":"Price of one, in minor units."},"amount":{"type":"integer","description":"This line in total: unit_amount × quantity, rounded half up once (minor units)."}},"required":["name","quantity","unit_amount","amount"]},"BillingDetails":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","description":"The name entered with the card."},"address":{"$ref":"#/components/schemas/BillingAddress"}},"required":["email","name","address"]},"BillingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"UnlockScheduleStep":{"type":"object","properties":{"step":{"type":"integer","description":"The step number, from 1, in order."},"days":{"type":"integer","nullable":true,"description":"Days after the payment succeeded. Null for payments that succeeded before unlock schedules existed."},"percent_bps":{"type":"integer","description":"Share of what the payment brings you, in basis points (8000 = 80 %)."},"available_at":{"type":"integer","description":"Unix seconds: when this step becomes available (a :00 or :30 mark, unless it was released early)."},"amount":{"type":"integer","description":"The step's part, in minor units, of what the payment brings you: amount_total less processing_fee and bank_fee (for fee_bearer buyer, that is the amount)."},"deducted":{"type":"integer","description":"What refunds (and their refund fees) took from this step."},"remaining":{"type":"integer","description":"amount − deducted."},"rescheduled":{"type":"boolean","description":"Whether its unlock time was changed by us."}},"required":["step","days","percent_bps","available_at","amount","deducted","remaining","rescheduled"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents/{id}":{"get":{"operationId":"retrievePaymentIntent","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Retrieve a payment intent","tags":["Payment intents"]}}}}
```

## List payment intents

> Newest first; \`order\_reference\` keeps only that order.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"PaymentIntentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentIntent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"PaymentIntent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_intent"]},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]},"currency":{"type":"string","enum":["usd","eur"]},"amount":{"type":"integer","description":"Amount before any buyer-paid fee, in minor units."},"fee_buyer":{"type":"integer","description":"Fees added to the total when the buyer bears them (processing_fee + bank_fee), else 0."},"amount_total":{"type":"integer","description":"Exactly what the buyer is charged and must be shown before paying (amount + fee_buyer)."},"processing_fee":{"type":"integer","description":"Processing fee of this payment, whoever bears it."},"bank_fee":{"type":"integer","description":"Bank fee of this payment, borne by the same party as the processing fee."},"fee_bearer":{"type":"string","enum":["merchant","buyer"]},"amount_refunded":{"type":"integer","description":"Refunded so far, refunds in flight included."},"amount_refundable":{"type":"integer","description":"What can still be refunded: amount_total less the processing and bank fees (fees are never refunded) less amount_refunded; 0 unless the payment succeeded."},"confirmation_attempts":{"type":"integer","description":"Payment attempts (confirms) sent so far. Each payment intent allows a limited number; once they are used, confirm answers `payment_intent_not_pending` and the buyer must restart checkout with a new payment intent."},"description":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"order_reference":{"type":"string","nullable":true,"description":"Your own number for the order; null until you send it. Required before the buyer pays."},"goods_type":{"type":"string","enum":["physical","non_physical"],"description":"`non_physical`: digital goods and services, nothing ships."},"buyer":{"nullable":true,"description":"Null until you send it. Required before the buyer pays.","type":"object","allOf":[{"$ref":"#/components/schemas/Buyer"}]},"shipping_details":{"nullable":true,"description":"Null until you send it. Required before the buyer pays, unless the goods are non_physical.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetails"}]},"items":{"description":"What the payment is for. Items describe the amount, they never set it.","type":"array","items":{"$ref":"#/components/schemas/PaymentItem"}},"shipping_amount":{"type":"integer","description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","description":"Declared discount, in minor units."},"items_difference":{"type":"integer","description":"`amount` − (the items' amounts + shipping_amount + tax_amount − discount_amount): 0 when your figures agree. Only reported: the payment is always charged for `amount`."},"billing_details":{"nullable":true,"description":"What the buyer entered with the card (the succeeded attempt's, else the latest attempt's); null before any attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/BillingDetails"}]},"client_secret":{"type":"string","description":"Only in the create response (and its idempotent replays). Pass it to the browser SDK."},"created":{"type":"integer","description":"Unix seconds."},"succeeded_at":{"type":"integer","nullable":true,"description":"Unix seconds."},"unlock_schedule":{"description":"The payment's unlock steps: when each part of what it brings you becomes available. Copied from your unlock schedule when the payment succeeds; empty before.","type":"array","items":{"$ref":"#/components/schemas/UnlockScheduleStep"}}},"required":["id","object","status","currency","amount","fee_buyer","amount_total","processing_fee","bank_fee","fee_bearer","amount_refunded","amount_refundable","confirmation_attempts","description","metadata","order_reference","goods_type","buyer","shipping_details","items","shipping_amount","tax_amount","discount_amount","items_difference","billing_details","created","succeeded_at","unlock_schedule"]},"Buyer":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ShippingDetails":{"type":"object","properties":{"name":{"type":"string","description":"The recipient."},"phone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/ShippingAddress"}},"required":["name","phone","address"]},"ShippingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"PaymentItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals."},"unit_amount":{"type":"integer","description":"Price of one, in minor units."},"amount":{"type":"integer","description":"This line in total: unit_amount × quantity, rounded half up once (minor units)."}},"required":["name","quantity","unit_amount","amount"]},"BillingDetails":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","description":"The name entered with the card."},"address":{"$ref":"#/components/schemas/BillingAddress"}},"required":["email","name","address"]},"BillingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"UnlockScheduleStep":{"type":"object","properties":{"step":{"type":"integer","description":"The step number, from 1, in order."},"days":{"type":"integer","nullable":true,"description":"Days after the payment succeeded. Null for payments that succeeded before unlock schedules existed."},"percent_bps":{"type":"integer","description":"Share of what the payment brings you, in basis points (8000 = 80 %)."},"available_at":{"type":"integer","description":"Unix seconds: when this step becomes available (a :00 or :30 mark, unless it was released early)."},"amount":{"type":"integer","description":"The step's part, in minor units, of what the payment brings you: amount_total less processing_fee and bank_fee (for fee_bearer buyer, that is the amount)."},"deducted":{"type":"integer","description":"What refunds (and their refund fees) took from this step."},"remaining":{"type":"integer","description":"amount − deducted."},"rescheduled":{"type":"boolean","description":"Whether its unlock time was changed by us."}},"required":["step","days","percent_bps","available_at","amount","deducted","remaining","rescheduled"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents":{"get":{"description":"Newest first; `order_reference` keeps only that order.","operationId":"listPaymentIntents","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"}},{"name":"starting_after","required":false,"in":"query","description":"Id of the last object of the previous page.","schema":{"type":"string"}},{"name":"order_reference","required":false,"in":"query","description":"Only payment intents carrying exactly this order reference.","schema":{"maxLength":100,"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentList"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"List payment intents","tags":["Payment intents"]}}}}
```

## Update the amount, currency, metadata or payment details of a pending payment intent

> Only while \`pending\`. A new \`amount\` or \`currency\` re-prices the fees with the fee schedule frozen on the intent; the change applies only once it is confirmed by the payment network (retry the same update after an error). A card form loaded before such a change must be loaded again: its confirm answers 409 \`payment\_intent\_updated\`. A new \`currency\` needs \`items\` again (and each declared amount that is not 0). \`metadata\` and the payment details (items, amounts, goods type, buyer, order reference, shipping details) replace their previous value whole and do not affect the card form. \`description\` cannot change. A suspended account gets a 400 \`merchant\_suspended\`.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"UpdatePaymentIntentRequest":{"type":"object","properties":{"items":{"minItems":1,"maxItems":100,"description":"What the payment is for (required on create). Items describe the amount, they never set it: only `amount` is priced and charged; the difference is reported as `items_difference`. On update: replaces the whole list, and must be sent again when the currency changes.","type":"array","items":{"$ref":"#/components/schemas/PaymentItemInput"}},"shipping_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","minimum":0,"maximum":99999999,"default":0,"description":"Declared discount, in minor units."},"goods_type":{"type":"string","enum":["physical","non_physical"],"default":"physical","description":"`non_physical`: digital goods and services, nothing ships. Only if your account may sell them."},"buyer":{"nullable":true,"description":"Required before the buyer pays (send it now or by update); null clears it on update.","type":"object","allOf":[{"$ref":"#/components/schemas/BuyerInput"}]},"order_reference":{"type":"string","nullable":true,"minLength":1,"maxLength":100,"description":"Your own number for the order (not unique). Required before the buyer pays; null clears it on update."},"shipping_details":{"nullable":true,"description":"Where the goods ship. Required before the buyer pays unless `goods_type` is `non_physical`; null clears it on update.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetailsInput"}]},"amount":{"type":"integer","minimum":1,"description":"New amount in minor units, before any buyer-paid fee. Fees are re-priced with the fee schedule frozen on the intent."},"currency":{"type":"string","enum":["usd","eur"],"description":"New currency; the amount stays as it is unless `amount` is sent too. Fees follow that currency's rules."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Replaces your whole key/value data (same limits as on create: at most 50 keys). Send {} to remove it."}}},"PaymentItemInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals, at most 1,000,000."},"unit_amount":{"type":"integer","minimum":0,"maximum":99999999,"description":"Price of one, in minor units."}},"required":["name","quantity","unit_amount"]},"BuyerInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200}},"required":["name"]},"ShippingDetailsInput":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"The recipient."},"phone":{"type":"string","nullable":true,"maxLength":40},"address":{"$ref":"#/components/schemas/ShippingAddressInput"}},"required":["name","address"]},"ShippingAddressInput":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","nullable":true,"maxLength":200},"city":{"type":"string","nullable":true,"maxLength":200},"state":{"type":"string","nullable":true,"maxLength":200},"postal_code":{"type":"string","nullable":true,"maxLength":20},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","country"]},"PaymentIntent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_intent"]},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]},"currency":{"type":"string","enum":["usd","eur"]},"amount":{"type":"integer","description":"Amount before any buyer-paid fee, in minor units."},"fee_buyer":{"type":"integer","description":"Fees added to the total when the buyer bears them (processing_fee + bank_fee), else 0."},"amount_total":{"type":"integer","description":"Exactly what the buyer is charged and must be shown before paying (amount + fee_buyer)."},"processing_fee":{"type":"integer","description":"Processing fee of this payment, whoever bears it."},"bank_fee":{"type":"integer","description":"Bank fee of this payment, borne by the same party as the processing fee."},"fee_bearer":{"type":"string","enum":["merchant","buyer"]},"amount_refunded":{"type":"integer","description":"Refunded so far, refunds in flight included."},"amount_refundable":{"type":"integer","description":"What can still be refunded: amount_total less the processing and bank fees (fees are never refunded) less amount_refunded; 0 unless the payment succeeded."},"confirmation_attempts":{"type":"integer","description":"Payment attempts (confirms) sent so far. Each payment intent allows a limited number; once they are used, confirm answers `payment_intent_not_pending` and the buyer must restart checkout with a new payment intent."},"description":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"order_reference":{"type":"string","nullable":true,"description":"Your own number for the order; null until you send it. Required before the buyer pays."},"goods_type":{"type":"string","enum":["physical","non_physical"],"description":"`non_physical`: digital goods and services, nothing ships."},"buyer":{"nullable":true,"description":"Null until you send it. Required before the buyer pays.","type":"object","allOf":[{"$ref":"#/components/schemas/Buyer"}]},"shipping_details":{"nullable":true,"description":"Null until you send it. Required before the buyer pays, unless the goods are non_physical.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetails"}]},"items":{"description":"What the payment is for. Items describe the amount, they never set it.","type":"array","items":{"$ref":"#/components/schemas/PaymentItem"}},"shipping_amount":{"type":"integer","description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","description":"Declared discount, in minor units."},"items_difference":{"type":"integer","description":"`amount` − (the items' amounts + shipping_amount + tax_amount − discount_amount): 0 when your figures agree. Only reported: the payment is always charged for `amount`."},"billing_details":{"nullable":true,"description":"What the buyer entered with the card (the succeeded attempt's, else the latest attempt's); null before any attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/BillingDetails"}]},"client_secret":{"type":"string","description":"Only in the create response (and its idempotent replays). Pass it to the browser SDK."},"created":{"type":"integer","description":"Unix seconds."},"succeeded_at":{"type":"integer","nullable":true,"description":"Unix seconds."},"unlock_schedule":{"description":"The payment's unlock steps: when each part of what it brings you becomes available. Copied from your unlock schedule when the payment succeeds; empty before.","type":"array","items":{"$ref":"#/components/schemas/UnlockScheduleStep"}}},"required":["id","object","status","currency","amount","fee_buyer","amount_total","processing_fee","bank_fee","fee_bearer","amount_refunded","amount_refundable","confirmation_attempts","description","metadata","order_reference","goods_type","buyer","shipping_details","items","shipping_amount","tax_amount","discount_amount","items_difference","billing_details","created","succeeded_at","unlock_schedule"]},"Buyer":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ShippingDetails":{"type":"object","properties":{"name":{"type":"string","description":"The recipient."},"phone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/ShippingAddress"}},"required":["name","phone","address"]},"ShippingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"PaymentItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals."},"unit_amount":{"type":"integer","description":"Price of one, in minor units."},"amount":{"type":"integer","description":"This line in total: unit_amount × quantity, rounded half up once (minor units)."}},"required":["name","quantity","unit_amount","amount"]},"BillingDetails":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","description":"The name entered with the card."},"address":{"$ref":"#/components/schemas/BillingAddress"}},"required":["email","name","address"]},"BillingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"UnlockScheduleStep":{"type":"object","properties":{"step":{"type":"integer","description":"The step number, from 1, in order."},"days":{"type":"integer","nullable":true,"description":"Days after the payment succeeded. Null for payments that succeeded before unlock schedules existed."},"percent_bps":{"type":"integer","description":"Share of what the payment brings you, in basis points (8000 = 80 %)."},"available_at":{"type":"integer","description":"Unix seconds: when this step becomes available (a :00 or :30 mark, unless it was released early)."},"amount":{"type":"integer","description":"The step's part, in minor units, of what the payment brings you: amount_total less processing_fee and bank_fee (for fee_bearer buyer, that is the amount)."},"deducted":{"type":"integer","description":"What refunds (and their refund fees) took from this step."},"remaining":{"type":"integer","description":"amount − deducted."},"rescheduled":{"type":"boolean","description":"Whether its unlock time was changed by us."}},"required":["step","days","percent_bps","available_at","amount","deducted","remaining","rescheduled"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents/{id}":{"post":{"description":"Only while `pending`. A new `amount` or `currency` re-prices the fees with the fee schedule frozen on the intent; the change applies only once it is confirmed by the payment network (retry the same update after an error). A card form loaded before such a change must be loaded again: its confirm answers 409 `payment_intent_updated`. A new `currency` needs `items` again (and each declared amount that is not 0). `metadata` and the payment details (items, amounts, goods type, buyer, order reference, shipping details) replace their previous value whole and do not affect the card form. `description` cannot change. A suspended account gets a 400 `merchant_suspended`.","operationId":"updatePaymentIntent","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentIntentRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"api_error: `internal_error`, or `fee_plan_not_configured` when no fee schedule applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"api_error: `provider_error`, the payment could not be processed; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Update the amount, currency, metadata or payment details of a pending payment intent","tags":["Payment intents"]}}}}
```

## Confirm a payment intent from your server

> Server-side confirm with a confirmation token created by the browser SDK, whose card form must have been loaded for the current amount: otherwise 409 \`payment\_intent\_updated\` (load the form again, then confirm). The payment must have its buyer, order reference and (physical goods) shipping details: otherwise 400 \`payment\_details\_missing\`, nothing is sent and no attempt is used. When \`next\_action\` is not null, run \`handleNextAction(next\_action.client\_secret)\` in the browser. Payment attempts are limited: each confirm sent counts, per payment intent (\`confirmation\_attempts\`; once they are used: 400 \`payment\_intent\_not\_pending\`, restart checkout with a new payment intent) and per account in 10-minute windows (429 \`rate\_limited\`, retry after \`Retry-After\` seconds).

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"ConfirmPaymentIntentRequest":{"type":"object","properties":{"confirmation_token":{"type":"string","description":"Confirmation token created by the browser SDK card form."},"billing_details":{"$ref":"#/components/schemas/BillingDetailsInput"},"return_url":{"type":"string","nullable":true,"description":"Absolute http(s) URL for redirect-based methods."}},"required":["confirmation_token","billing_details"]},"BillingDetailsInput":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/BillingAddressInput"}},"required":["email","name","address"]},"BillingAddressInput":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","postal_code","country"]},"ConfirmResponse":{"type":"object","properties":{"payment_intent":{"$ref":"#/components/schemas/PaymentIntentSummary"},"next_action":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/NextAction"}]}},"required":["payment_intent","next_action"]},"PaymentIntentSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]}},"required":["id","status"]},"NextAction":{"type":"object","properties":{"type":{"type":"string","enum":["handle_next_action"]},"client_secret":{"type":"string","description":"Pass to handleNextAction() in the browser SDK."}},"required":["type","client_secret"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents/{id}/confirm":{"post":{"description":"Server-side confirm with a confirmation token created by the browser SDK, whose card form must have been loaded for the current amount: otherwise 409 `payment_intent_updated` (load the form again, then confirm). The payment must have its buyer, order reference and (physical goods) shipping details: otherwise 400 `payment_details_missing`, nothing is sent and no attempt is used. When `next_action` is not null, run `handleNextAction(next_action.client_secret)` in the browser. Payment attempts are limited: each confirm sent counts, per payment intent (`confirmation_attempts`; once they are used: 400 `payment_intent_not_pending`, restart checkout with a new payment intent) and per account in 10-minute windows (429 `rate_limited`, retry after `Retry-After` seconds).","operationId":"confirmPaymentIntent","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPaymentIntentRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmResponse"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"card_error: the payment method was declined (`decline_code` when known) or the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"invalid_request_error: `idempotency_key_reused`, or `payment_intent_updated` on confirm (the amount changed since the card form was loaded: load the form again, then confirm).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"api_error: `provider_error`, the payment could not be processed; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Confirm a payment intent from your server","tags":["Payment intents"]}}}}
```

## Release a payment attempt after a failed confirmation, from your server

> Same as the client release: lets the buyer try again after a declined attempt. Returns the status now in force; a succeeded or canceled payment intent is never changed.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Payment intents","description":"Create, update and confirm payments from your server (secret key)."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"ReleaseResponse":{"type":"object","properties":{"payment_intent":{"$ref":"#/components/schemas/PaymentIntentSummary"}},"required":["payment_intent"]},"PaymentIntentSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]}},"required":["id","status"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/payment_intents/{id}/release":{"post":{"description":"Same as the client release: lets the buyer try again after a declined attempt. Returns the status now in force; a succeeded or canceled payment intent is never changed.","operationId":"releasePaymentIntent","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseResponse"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"card_error: the payment method was declined (`decline_code` when known) or the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"api_error: `provider_error`, the payment could not be processed; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Release a payment attempt after a failed confirmation, from your server","tags":["Payment intents"]}}}}
```

## The payment intent object

## The PaymentIntent object

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"components":{"schemas":{"PaymentIntent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_intent"]},"status":{"type":"string","enum":["pending","processing","succeeded","canceled"]},"currency":{"type":"string","enum":["usd","eur"]},"amount":{"type":"integer","description":"Amount before any buyer-paid fee, in minor units."},"fee_buyer":{"type":"integer","description":"Fees added to the total when the buyer bears them (processing_fee + bank_fee), else 0."},"amount_total":{"type":"integer","description":"Exactly what the buyer is charged and must be shown before paying (amount + fee_buyer)."},"processing_fee":{"type":"integer","description":"Processing fee of this payment, whoever bears it."},"bank_fee":{"type":"integer","description":"Bank fee of this payment, borne by the same party as the processing fee."},"fee_bearer":{"type":"string","enum":["merchant","buyer"]},"amount_refunded":{"type":"integer","description":"Refunded so far, refunds in flight included."},"amount_refundable":{"type":"integer","description":"What can still be refunded: amount_total less the processing and bank fees (fees are never refunded) less amount_refunded; 0 unless the payment succeeded."},"confirmation_attempts":{"type":"integer","description":"Payment attempts (confirms) sent so far. Each payment intent allows a limited number; once they are used, confirm answers `payment_intent_not_pending` and the buyer must restart checkout with a new payment intent."},"description":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"order_reference":{"type":"string","nullable":true,"description":"Your own number for the order; null until you send it. Required before the buyer pays."},"goods_type":{"type":"string","enum":["physical","non_physical"],"description":"`non_physical`: digital goods and services, nothing ships."},"buyer":{"nullable":true,"description":"Null until you send it. Required before the buyer pays.","type":"object","allOf":[{"$ref":"#/components/schemas/Buyer"}]},"shipping_details":{"nullable":true,"description":"Null until you send it. Required before the buyer pays, unless the goods are non_physical.","type":"object","allOf":[{"$ref":"#/components/schemas/ShippingDetails"}]},"items":{"description":"What the payment is for. Items describe the amount, they never set it.","type":"array","items":{"$ref":"#/components/schemas/PaymentItem"}},"shipping_amount":{"type":"integer","description":"Declared shipping, in minor units."},"tax_amount":{"type":"integer","description":"Declared tax, in minor units."},"discount_amount":{"type":"integer","description":"Declared discount, in minor units."},"items_difference":{"type":"integer","description":"`amount` − (the items' amounts + shipping_amount + tax_amount − discount_amount): 0 when your figures agree. Only reported: the payment is always charged for `amount`."},"billing_details":{"nullable":true,"description":"What the buyer entered with the card (the succeeded attempt's, else the latest attempt's); null before any attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/BillingDetails"}]},"client_secret":{"type":"string","description":"Only in the create response (and its idempotent replays). Pass it to the browser SDK."},"created":{"type":"integer","description":"Unix seconds."},"succeeded_at":{"type":"integer","nullable":true,"description":"Unix seconds."},"unlock_schedule":{"description":"The payment's unlock steps: when each part of what it brings you becomes available. Copied from your unlock schedule when the payment succeeds; empty before.","type":"array","items":{"$ref":"#/components/schemas/UnlockScheduleStep"}}},"required":["id","object","status","currency","amount","fee_buyer","amount_total","processing_fee","bank_fee","fee_bearer","amount_refunded","amount_refundable","confirmation_attempts","description","metadata","order_reference","goods_type","buyer","shipping_details","items","shipping_amount","tax_amount","discount_amount","items_difference","billing_details","created","succeeded_at","unlock_schedule"]},"Buyer":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ShippingDetails":{"type":"object","properties":{"name":{"type":"string","description":"The recipient."},"phone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/ShippingAddress"}},"required":["name","phone","address"]},"ShippingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"PaymentItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number","description":"Greater than 0, at most 3 decimals."},"unit_amount":{"type":"integer","description":"Price of one, in minor units."},"amount":{"type":"integer","description":"This line in total: unit_amount × quantity, rounded half up once (minor units)."}},"required":["name","quantity","unit_amount","amount"]},"BillingDetails":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","description":"The name entered with the card."},"address":{"$ref":"#/components/schemas/BillingAddress"}},"required":["email","name","address"]},"BillingAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}},"required":["line1","line2","city","state","postal_code","country"]},"UnlockScheduleStep":{"type":"object","properties":{"step":{"type":"integer","description":"The step number, from 1, in order."},"days":{"type":"integer","nullable":true,"description":"Days after the payment succeeded. Null for payments that succeeded before unlock schedules existed."},"percent_bps":{"type":"integer","description":"Share of what the payment brings you, in basis points (8000 = 80 %)."},"available_at":{"type":"integer","description":"Unix seconds: when this step becomes available (a :00 or :30 mark, unless it was released early)."},"amount":{"type":"integer","description":"The step's part, in minor units, of what the payment brings you: amount_total less processing_fee and bank_fee (for fee_bearer buyer, that is the amount)."},"deducted":{"type":"integer","description":"What refunds (and their refund fees) took from this step."},"remaining":{"type":"integer","description":"amount − deducted."},"rescheduled":{"type":"boolean","description":"Whether its unlock time was changed by us."}},"required":["step","days","percent_bps","available_at","amount","deducted","remaining","rescheduled"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.loomgate.io/en/api-reference/payment-intents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.