> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/payments.md).

# Payments

Payment management

## List payments

> Retrieve a paginated list of payments

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"payments","description":"Payment management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["payments"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"OrderPayment":{"type":"object","properties":{"id":{"type":"integer","description":"Payment ID"},"order_id":{"type":"integer","description":"Associated order ID"},"customer_id":{"type":"integer","nullable":true,"description":"Customer who made the payment (sourced from the parent order; included for convenience so customer-centric reporting doesn't require a second hop through /v2/orders)"},"source_id":{"type":"integer","nullable":true,"description":"Payment source (card) ID (database field)"},"source":{"type":"object","properties":{"id":{"type":"integer","description":"Payment source ID"},"card_id":{"type":"integer","description":"Customer card ID"},"gateway_id":{"type":"integer","description":"Payment gateway ID"},"stripe_source_id":{"type":"string","nullable":true,"description":"Stripe source ID"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"description":"Stripe payment method ID"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"description":"PayPal billing agreement ID"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"stripe_customer_id":{"type":"string","nullable":true,"description":"Stripe customer ID"},"paypal_payer_id":{"type":"string","nullable":true,"description":"PayPal payer ID"},"paypal_customer_id":{"type":"string","nullable":true,"description":"PayPal customer ID"},"paypal_token_id":{"type":"string","nullable":true,"description":"PayPal token ID"},"nmi_customer_vault_id":{"type":"string","nullable":true,"description":"NMI customer vault ID"},"authentication":{"nullable":true,"description":"3D Secure authentication data"},"customer_id":{"type":"integer","description":"Customer ID who owns this source"},"is_active":{"type":"boolean","description":"Whether this source is active"},"is_three_d_secure_supported":{"type":"boolean","description":"Whether 3D Secure is supported"},"type":{"type":"string","nullable":true,"description":"Card brand (visa, mastercard, etc.)"},"last_four":{"type":"string","nullable":true,"description":"Last 4 digits of card number"},"exp_month":{"type":"string","nullable":true,"description":"Expiration month (MM)"},"exp_year":{"type":"string","nullable":true,"description":"Expiration year (YYYY)"},"address_zip":{"type":"string","nullable":true,"description":"Card billing ZIP/postal code"},"country":{"type":"string","nullable":true,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"description":"Card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"description":"Billing city"},"address_state":{"type":"string","nullable":true,"description":"Billing state/province"},"address_country":{"type":"string","nullable":true,"description":"Billing country code"}},"required":["id","card_id","gateway_id","customer_id"],"description":"Payment source (card) object"},"gateway_id":{"type":"integer","nullable":true,"description":"Payment gateway ID"},"initial_payment_id":{"type":"integer","nullable":true,"description":"Initial payment ID (for retries)"},"stripe_charge_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe charge ID"},"stripe_invoice_id":{"type":"string","nullable":true,"description":"Stripe invoice ID"},"stripe_paymentintent_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentIntent ID"},"paypal_order_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal order ID"},"paypal_capture_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal capture ID"},"is_manual":{"type":"boolean","nullable":true,"description":"Whether payment was manually recorded"},"is_3ds_in_progress":{"type":"boolean","description":"Whether 3D Secure authentication is in progress"},"amount":{"type":"integer","description":"Total payment amount in cents"},"amount_paid":{"type":"integer","description":"Amount successfully paid in cents"},"amount_refunded":{"type":"integer","description":"Amount refunded in cents"},"currency":{"type":"string","nullable":true,"enum":["aud","cad","usd","gbp","eur","sgd","aed","afn","all","amd","ang","aoa","ars","awg","azn","bam","bbd","bdt","bgn","bif","bmd","bnd","bob","brl","bsd","bwp","bzd","cdf","chf","clp","cny","cop","crc","cve","czk","djf","dkk","dop","dzd","egp","etb","fjd","fkp","gel","gip","gmd","gnf","gtq","gyd","hkd","hnl","hrk","htg","huf","idr","ils","inr","isk","jmd","jpy","kes","kgs","khr","kmf","krw","kyd","kzt","lak","lbp","lkr","lrd","lsl","mad","mdl","mga","mkd","mmk","mnt","mop","mro","mur","mvr","mwk","mxn","myr","mzn","nad","ngn","nio","nok","npr","nzd","pab","pen","pgk","php","pkr","pln","pyg","qar","ron","rsd","rub","rwf","sar","sbd","scr","sek","shp","sll","sos","srd","std","szl","thb","tjs","top","try","ttd","twd","tzs","uah","ugx","uyu","uzs","vnd","vuv","wst","xaf","xcd","xof","xpf","yer","zar","zmw",null],"description":"Payment currency code"},"failure_reason":{"type":"string","nullable":true,"description":"Human-readable failure reason"},"has_pending_retry":{"type":"boolean","description":"Whether a retry is pending"},"refunded_at":{"type":"string","nullable":true,"format":"date-time","description":"Refund timestamp"},"status":{"type":"string","nullable":true,"enum":["pending","succeeded","failed","refunded","disputed","dispute_refunded",null],"description":"Payment status"},"is_3ds":{"type":"boolean","description":"Whether 3D Secure was used"},"can_skip":{"type":"boolean","description":"Whether payment can be skipped"},"nmi_transaction_id":{"type":"string","nullable":true,"maxLength":255,"description":"NMI transaction ID"},"is_startup_fee":{"type":"boolean","description":"Whether this is a startup/setup fee"},"failure_code":{"type":"string","nullable":true,"maxLength":255,"description":"Gateway-specific failure code"},"payment_method_type":{"type":"string","nullable":true,"maxLength":255,"description":"What actually paid this charge, as the gateway reports it (e.g. card, apple_pay, klarna, afterpay_clearpay). Null when unknown or not recorded — clients should fall back to the card display."},"financing_installments_count":{"type":"integer","nullable":true,"description":"Number of installments for a financing (BNPL) payment. Null for non-financing payments."},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"initial_payment_id":{"type":"integer","nullable":true},"amount":{"type":"integer"},"amount_paid":{"type":"integer"},"amount_refunded":{"type":"integer"},"currency":{"type":"string","nullable":true},"status":{"type":"string"},"failure_reason":{"type":"string","nullable":true},"has_pending_retry":{"type":"boolean","nullable":true},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id"]},"description":"Payment retry attempts"}},"required":["id","order_id","amount_paid"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/payments":{"get":{"tags":["payments"],"summary":"List payments","description":"Retrieve a paginated list of payments","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Items per page (max 100)"},"required":false,"description":"Items per page (max 100)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of expansions: customer, order"},"required":false,"description":"Comma-separated list of expansions: customer, order","name":"include","in":"query"},{"schema":{"type":"string","description":"Filter by status (exact match). Valid values: pending, succeeded, failed, refunded, disputed, dispute_refunded."},"required":false,"description":"Filter by status (exact match). Valid values: pending, succeeded, failed, refunded, disputed, dispute_refunded.","name":"filter[status]","in":"query"},{"schema":{"type":"string","description":"Filter by status (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by status (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[status.in]","in":"query"},{"schema":{"type":"string","description":"Filter by status (excluding a comma-separated list)"},"required":false,"description":"Filter by status (excluding a comma-separated list)","name":"filter[status.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (exact match)."},"required":false,"description":"Filter by order_id (exact match).","name":"filter[order_id]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (greater than or equal)"},"required":false,"description":"Filter by order_id (greater than or equal)","name":"filter[order_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (less than or equal)"},"required":false,"description":"Filter by order_id (less than or equal)","name":"filter[order_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by order_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[order_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (excluding a comma-separated list)"},"required":false,"description":"Filter by order_id (excluding a comma-separated list)","name":"filter[order_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (exact match)."},"required":false,"description":"Filter by customer_id (exact match).","name":"filter[customer_id]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (greater than or equal)"},"required":false,"description":"Filter by customer_id (greater than or equal)","name":"filter[customer_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (less than or equal)"},"required":false,"description":"Filter by customer_id (less than or equal)","name":"filter[customer_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by customer_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[customer_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (excluding a comma-separated list)"},"required":false,"description":"Filter by customer_id (excluding a comma-separated list)","name":"filter[customer_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by gateway_id (exact match)."},"required":false,"description":"Filter by gateway_id (exact match).","name":"filter[gateway_id]","in":"query"},{"schema":{"type":"string","description":"Filter by gateway_id (greater than or equal)"},"required":false,"description":"Filter by gateway_id (greater than or equal)","name":"filter[gateway_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by gateway_id (less than or equal)"},"required":false,"description":"Filter by gateway_id (less than or equal)","name":"filter[gateway_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by gateway_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by gateway_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[gateway_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by gateway_id (excluding a comma-separated list)"},"required":false,"description":"Filter by gateway_id (excluding a comma-separated list)","name":"filter[gateway_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by currency (exact match)."},"required":false,"description":"Filter by currency (exact match).","name":"filter[currency]","in":"query"},{"schema":{"type":"string","description":"Filter by currency (contains)"},"required":false,"description":"Filter by currency (contains)","name":"filter[currency.contains]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (exact match)."},"required":false,"description":"Filter by created_at (exact match).","name":"filter[created_at]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (greater than or equal)"},"required":false,"description":"Filter by created_at (greater than or equal)","name":"filter[created_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (less than or equal)"},"required":false,"description":"Filter by created_at (less than or equal)","name":"filter[created_at.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (exact match)."},"required":false,"description":"Filter by updated_at (exact match).","name":"filter[updated_at]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (greater than or equal)"},"required":false,"description":"Filter by updated_at (greater than or equal)","name":"filter[updated_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (less than or equal)"},"required":false,"description":"Filter by updated_at (less than or equal)","name":"filter[updated_at.lte]","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"}],"responses":{"200":{"description":"Successful response with paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderPayment"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Current page number"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["page","limit","total","pages"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retrieve a payment

> Retrieve a single payments by ID

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"payments","description":"Payment management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["payments"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"OrderPayment":{"type":"object","properties":{"id":{"type":"integer","description":"Payment ID"},"order_id":{"type":"integer","description":"Associated order ID"},"customer_id":{"type":"integer","nullable":true,"description":"Customer who made the payment (sourced from the parent order; included for convenience so customer-centric reporting doesn't require a second hop through /v2/orders)"},"source_id":{"type":"integer","nullable":true,"description":"Payment source (card) ID (database field)"},"source":{"type":"object","properties":{"id":{"type":"integer","description":"Payment source ID"},"card_id":{"type":"integer","description":"Customer card ID"},"gateway_id":{"type":"integer","description":"Payment gateway ID"},"stripe_source_id":{"type":"string","nullable":true,"description":"Stripe source ID"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"description":"Stripe payment method ID"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"description":"PayPal billing agreement ID"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"stripe_customer_id":{"type":"string","nullable":true,"description":"Stripe customer ID"},"paypal_payer_id":{"type":"string","nullable":true,"description":"PayPal payer ID"},"paypal_customer_id":{"type":"string","nullable":true,"description":"PayPal customer ID"},"paypal_token_id":{"type":"string","nullable":true,"description":"PayPal token ID"},"nmi_customer_vault_id":{"type":"string","nullable":true,"description":"NMI customer vault ID"},"authentication":{"nullable":true,"description":"3D Secure authentication data"},"customer_id":{"type":"integer","description":"Customer ID who owns this source"},"is_active":{"type":"boolean","description":"Whether this source is active"},"is_three_d_secure_supported":{"type":"boolean","description":"Whether 3D Secure is supported"},"type":{"type":"string","nullable":true,"description":"Card brand (visa, mastercard, etc.)"},"last_four":{"type":"string","nullable":true,"description":"Last 4 digits of card number"},"exp_month":{"type":"string","nullable":true,"description":"Expiration month (MM)"},"exp_year":{"type":"string","nullable":true,"description":"Expiration year (YYYY)"},"address_zip":{"type":"string","nullable":true,"description":"Card billing ZIP/postal code"},"country":{"type":"string","nullable":true,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"description":"Card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"description":"Billing city"},"address_state":{"type":"string","nullable":true,"description":"Billing state/province"},"address_country":{"type":"string","nullable":true,"description":"Billing country code"}},"required":["id","card_id","gateway_id","customer_id"],"description":"Payment source (card) object"},"gateway_id":{"type":"integer","nullable":true,"description":"Payment gateway ID"},"initial_payment_id":{"type":"integer","nullable":true,"description":"Initial payment ID (for retries)"},"stripe_charge_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe charge ID"},"stripe_invoice_id":{"type":"string","nullable":true,"description":"Stripe invoice ID"},"stripe_paymentintent_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentIntent ID"},"paypal_order_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal order ID"},"paypal_capture_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal capture ID"},"is_manual":{"type":"boolean","nullable":true,"description":"Whether payment was manually recorded"},"is_3ds_in_progress":{"type":"boolean","description":"Whether 3D Secure authentication is in progress"},"amount":{"type":"integer","description":"Total payment amount in cents"},"amount_paid":{"type":"integer","description":"Amount successfully paid in cents"},"amount_refunded":{"type":"integer","description":"Amount refunded in cents"},"currency":{"type":"string","nullable":true,"enum":["aud","cad","usd","gbp","eur","sgd","aed","afn","all","amd","ang","aoa","ars","awg","azn","bam","bbd","bdt","bgn","bif","bmd","bnd","bob","brl","bsd","bwp","bzd","cdf","chf","clp","cny","cop","crc","cve","czk","djf","dkk","dop","dzd","egp","etb","fjd","fkp","gel","gip","gmd","gnf","gtq","gyd","hkd","hnl","hrk","htg","huf","idr","ils","inr","isk","jmd","jpy","kes","kgs","khr","kmf","krw","kyd","kzt","lak","lbp","lkr","lrd","lsl","mad","mdl","mga","mkd","mmk","mnt","mop","mro","mur","mvr","mwk","mxn","myr","mzn","nad","ngn","nio","nok","npr","nzd","pab","pen","pgk","php","pkr","pln","pyg","qar","ron","rsd","rub","rwf","sar","sbd","scr","sek","shp","sll","sos","srd","std","szl","thb","tjs","top","try","ttd","twd","tzs","uah","ugx","uyu","uzs","vnd","vuv","wst","xaf","xcd","xof","xpf","yer","zar","zmw",null],"description":"Payment currency code"},"failure_reason":{"type":"string","nullable":true,"description":"Human-readable failure reason"},"has_pending_retry":{"type":"boolean","description":"Whether a retry is pending"},"refunded_at":{"type":"string","nullable":true,"format":"date-time","description":"Refund timestamp"},"status":{"type":"string","nullable":true,"enum":["pending","succeeded","failed","refunded","disputed","dispute_refunded",null],"description":"Payment status"},"is_3ds":{"type":"boolean","description":"Whether 3D Secure was used"},"can_skip":{"type":"boolean","description":"Whether payment can be skipped"},"nmi_transaction_id":{"type":"string","nullable":true,"maxLength":255,"description":"NMI transaction ID"},"is_startup_fee":{"type":"boolean","description":"Whether this is a startup/setup fee"},"failure_code":{"type":"string","nullable":true,"maxLength":255,"description":"Gateway-specific failure code"},"payment_method_type":{"type":"string","nullable":true,"maxLength":255,"description":"What actually paid this charge, as the gateway reports it (e.g. card, apple_pay, klarna, afterpay_clearpay). Null when unknown or not recorded — clients should fall back to the card display."},"financing_installments_count":{"type":"integer","nullable":true,"description":"Number of installments for a financing (BNPL) payment. Null for non-financing payments."},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"initial_payment_id":{"type":"integer","nullable":true},"amount":{"type":"integer"},"amount_paid":{"type":"integer"},"amount_refunded":{"type":"integer"},"currency":{"type":"string","nullable":true},"status":{"type":"string"},"failure_reason":{"type":"string","nullable":true},"has_pending_retry":{"type":"boolean","nullable":true},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id"]},"description":"Payment retry attempts"}},"required":["id","order_id","amount_paid"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/payments/{id}":{"get":{"tags":["payments"],"summary":"Retrieve a payment","description":"Retrieve a single payments by ID","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"payments ID"},"required":true,"description":"payments ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of expansions: customer, order"},"required":false,"description":"Comma-separated list of expansions: customer, order","name":"include","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPayment"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Refund a payment

> Refund a payment on an order. \`refund\_amount\` is required — pass the payment's full remaining refundable balance for a full refund.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"payments","description":"Payment management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["payments"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/payments/{id}/refund":{"post":{"tags":["payments"],"summary":"Refund a payment","description":"Refund a payment on an order. `refund_amount` is required — pass the payment's full remaining refundable balance for a full refund.","parameters":[{"schema":{"type":"string","description":"Payment ID"},"required":true,"description":"Payment ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refund_amount":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Amount to refund as a whole number of the smallest currency unit ($10.00 USD = 1000; ¥1500 JPY = 1500). Fractions are rejected. Must not exceed the payment's remaining refundable balance."},"items":{"type":"array","items":{"type":"number"},"description":"Array of order item IDs to mark as refunded"},"do_affiliate_adjustment":{"type":"boolean","description":"Whether to adjust affiliate commissions"},"skip_integration_actions":{"type":"boolean","description":"Skip the merchant's own automations for this refund. The refund is still recorded and order-sync integrations (tax, CRM deal and contact sync) still run. Developer-platform Event Webhooks are still delivered; the merchant's own \"Send Webhook\" automation action is an automation and does NOT run. The choice is stored on the payment, so a later refund of the same payment made outside Spiffy inherits it — the last choice made through Spiffy wins."},"notes":{"type":"string","description":"Internal notes for the refund"}},"required":["refund_amount"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retry a failed payment

> Queue a retry for a failed payment. Only the original failed payment (not subsequent attempts) can be retried.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"payments","description":"Payment management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["payments"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/payments/{id}/retry":{"post":{"tags":["payments"],"summary":"Retry a failed payment","description":"Queue a retry for a failed payment. Only the original failed payment (not subsequent attempts) can be retried.","parameters":[{"schema":{"type":"string","description":"Payment ID"},"required":true,"description":"Payment ID","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```
