Documentation Index Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
A sale authorizes and captures a payment in one request. Use this endpoint when you want to immediately charge the customer without a separate capture step.
Safe retries for this POST endpoint use the Idempotency-Key header. Reuse the same key only when retrying the exact same request body. See Idempotency . curl --request POST \ --url https://api.smartretry.com/v1/payments/sale/ABC123 \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: sale-order-20260331-001' \ --data '{ "merchant_transaction_id": "order-20260331-001", "amount": 49.99, "currency": "USD", "order": { "merchant_order_id": "my-order-20260331-001", "payment_instrument": { "card_number": "4111111111111111", "expiry_month": 12, "expiry_year": 2027, "payment_method": "cards", "card_cardholder_name": "Jane Doe" }, "payer": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" }, "description": "Order #20260331-001" }, "cvv": "123" }'
{ "transaction_id" : "TX8A3F2C" , "order_id" : "OR7B9E1D" , "merchant_transaction_id" : "order-20260331-001" , "accepted" : true }
Path parameters Your terminal identifier. Exactly 6 characters.
Request body Your unique identifier for this transaction. Use this to correlate SmartRetry transactions with your own records. Maximum 100 characters.
Amount to charge in major currency units (e.g., 49.99 for $49.99). Minimum 1, maximum 999999999.
Three-letter ISO 4217 currency code (e.g., USD, EUR, GBP). Order details, including payer identity and payment instrument. Your own order reference. Maximum 100 characters.
Card or payment method details. Required when not using a top-level token. Primary account number (PAN). Between 13 and 19 digits.
Card expiry month. Integer between 1 and 12.
Card expiry year. Integer between 2024 and 2099.
Payment method type. One of: cards, digital_wallets, bnpl, online_banking, rtp, vouchers, cash, direct_debit, cryptocurrencies.
Name as it appears on the card. Maximum 100 characters.
Stored card profile fingerprint. Exactly 88 characters.
Payer identity details. Payer’s first name. Maximum 50 characters.
Payer’s last name. Maximum 50 characters.
Payer’s email address. Maximum 254 characters.
SmartRetry payer ID. Exactly 8 characters. Provide this to link the transaction to an existing payer profile.
Payer’s phone number in E.164 format (e.g., +12125551234). Payer’s billing address. Apartment, suite, or unit number.
State or province code in ISO 3166-2 format (e.g., US-CA). Human-readable description of the order. Maximum 500 characters.
Stored payment token (88 characters). Use this instead of order.payment_instrument.card_number for repeat customers.
Card verification value (CVV/CVC). Optional but recommended for card-not-present transactions. The CVV is never stored by SmartRetry and cannot be used in tokenized or retry flows.
Human-readable description of the transaction. Maximum 500 characters.
SmartRetry order ID (exactly 8 characters). Provide this to associate the transaction with an existing order.
IPv4 address of the payer making the request. Used for fraud detection.
Device and browser details for 3DS and fraud scoring. Device fingerprint. Exactly 88 characters.
Operating system name. Maximum 50 characters.
Operating system version. Maximum 20 characters.
Browser name. Maximum 50 characters.
Browser version. Maximum 20 characters.
Browser language as a 3-letter ISO 639-3 code.
Shipping indicator for 3DS authentication.
delivery_address_usage_indicator
Indicates how long the shipping address has been associated with the customer. Used for 3DS.
Indicates the delivery timeframe for the order. Used for 3DS.
Shipping recipient details. Used for 3DS and fraud checks. Recipient’s first name. Maximum 50 characters.
Recipient’s last name. Maximum 50 characters.
Recipient’s full name. Maximum 150 characters.
SmartRetry payer ID of the recipient. Exactly 8 characters.
Response SmartRetry’s unique identifier for this transaction. Exactly 8 characters. Use this in subsequent capture , refund , or void requests. SmartRetry’s unique identifier for the order. Exactly 8 characters.
The merchant_transaction_id you provided in the request, echoed back for confirmation.
true if the transaction was accepted for processing. A value of true does not guarantee approval - poll the status endpoint to confirm the final outcome.accepted: true means SmartRetry has accepted the transaction for processing. To confirm whether the payment was approved by the issuer, fetch the transaction status using the returned transaction_id.
