Create a payment
Charges a customer an amount you set, with no cart or invoice. Send currency and one of total, subtotal or shipping; amounts cannot be negative. To pay for a cart or an invoice, use POST /carts/{cart_id}/payments or POST /invoices/{invoice_id}/payments instead. An account on the reseller model can only use this to add to a customer's balance (apply_to_balance). A live payment needs a live account (422).
Any token type may call it. A limited token is bound to the payment it makes, and a limited test token only works when its user may make test payments. capture is ignored for a limited token.
The answer is 201 with status completed, pending (authorized only), processing or initiated (the shopper must act: see response_data, then commit it while it is still initiated). A declined payment is 402 with the payment in error.meta.payment. The same payment sent again soon after a success is 409 (code duplicate).
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
expand?stringComma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.
formatted?booleanWhen true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.
falseuser_ip_address?stringThe shopper's IP address, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks and to find the shopper's country. Only read for a secret token: for every other token the address the request comes from is used. A value that is not a valid IPv4 or IPv6 address is ignored.
user_agent?stringThe shopper's browser user agent, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks. Only read for a secret token: for every other token the request's own User-Agent header is used.
A payment request object.
application/json- body
A payment to make. For a cart (POST /carts/{cart_id}/payments) the amount and currency come from the cart, so you send only who pays and how. For an invoice you may send a total to pay part of it. For a payment with no cart or invoice (POST /payments) you send the amount and currency.
payment_id?stringYour own id for the payment. Letters, numbers, underscores, dashes and periods, not used before. Assigned for you when left out.
length <= 30customer_id?stringAn existing customer who pays. Send this or customer, not both. For a cart or invoice it must be the cart's or invoice's customer, and can be left out.
customer?The customer's details. To change an existing customer, include its customer_id. Send this or customer_id, not both.
payment_method_id?stringA saved payment method of the customer. Send this or payment_method, not both. With neither, the customer's default method is used, and the request fails when there is none.
payment_method?How the customer pays: a type (credit_card, paypal, amazon_pay, apple_pay, ach, stripe, wallet or customer_account_balance) and its data. Your account needs a gateway for that type in the payment currency.
currency?stringThe ISO 4217 currency. Required for a payment with no cart or invoice. Not allowed for a cart or an invoice (error i1pLDWP or DQQa1EN).
total?numberThe amount to charge. For a payment with no cart or invoice, send total, subtotal or shipping. For an invoice, an amount up to what is left to pay. Not allowed for a cart (error i1pLDWP).
0 <= valuesubtotal?numberOnly for a payment with no cart or invoice. When sent, total is worked out as subtotal plus tax plus shipping. When you send both subtotal and total, the sum must match.
0 <= valuetax?numberOnly for a payment with no cart or invoice. Defaults to 0.
0 <= valueshipping?numberOnly for a payment with no cart or invoice. Defaults to 0.
0 <= valuecapture?booleanFor card, PayPal, Amazon Pay, Comecero Express Payments and wallet payments: true to capture at once, false to only authorize (the payment is then pending). Left out, your fulfillment settings decide. Ignored for a limited token.
description?stringYour description of the payment.
length <= 256reference?stringYour own reference for the payment.
length <= 100apply_to_balance?booleanOnly for a payment with no cart or invoice. True adds the captured total to the customer's store credit balance. Ignored when the payment method is customer_account_balance. It is also what lets an account on the reseller model take a payment with no cart or invoice.
gateway_id?stringUse this gateway instead of letting Comecero choose. It must be an active gateway of your own. Not allowed on an account on the reseller model.
return_url?stringWhere the shopper's browser comes back to after a bank check on the card gateway's own page (PayPal card payments). {{payment_id}} in it is replaced with the payment id. An absolute https address; in test mode http on localhost is allowed too. Without a usable one, a payment that needs such a check is declined. Not stored or returned.
urilength <= 2000risk_session_id?stringThe PayPal FraudNet session id from the browser, when the card option has paypal_fraudnet_source_id. 16 to 36 letters, digits or dashes. A value that does not fit is ignored. Not stored or returned.
device_session_id?stringThe Stripe Radar session id (rse_...) made in the browser, when the card option has stripe_publishable_key. A value that does not fit is ignored. Not stored or returned.
ignore_bad_avs?booleanOnly for secret and trusted tokens. True lets a card payment go ahead when the address check fails.
merchant_descriptor?stringOnly for an account on the agent model with a secret or trusted token. The text on the shopper's card statement. Defaults to your payment settings.
merchant_contact?stringOnly for an account on the agent model with a secret or trusted token. The contact shown with the statement text.
meta?||Your own data for the payment, a string or an object, up to 2048 characters.
The payment.
application/json- response
Money taken, or being taken, from a customer. status says where the payment is. A payment that needs the shopper to act (PayPal approval, a 3-D Secure check, a Comecero Express Payments confirmation) comes back initiated with what to do in response_data; you finish it with POST /payments/{payment_id}/commit. A limited token does not see the gateway fields or the settlement amounts.
object*"payment"The object type. Always payment.
"payment"url*stringThe full URL of the payment.
uripayment_id*stringThe id of the payment.
account_id*stringThe account the payment belongs to.
success*booleanTrue when the gateway accepted the payment or the step so far. True for initiated, processing, pending, completed and cancelled; false for failed.
status*stringinitiated: created, waiting for the shopper to approve or pass a check; commit it when they are done. processing: the gateway has it and will answer later (for example ACH); the cart or invoice cannot change meanwhile. pending: authorized, not yet captured; capture or void it. completed: captured. failed: declined or in error. cancelled: voided. refunded and retry are also valid values of the status filter.
"initiated""processing""pending""completed""failed""cancelled""refunded""retry"date_created*stringWhen the payment was created.
date-timedate_modified*stringWhen the payment was last changed.
date-timedate_completed*|When the payment was captured, or null if it is not.
date-timetest*booleanTrue for a test payment.
currency*stringThe ISO 4217 currency of the payment.
subtotal*numberThe amount without tax and shipping, in currency.
shipping*numberThe shipping amount without tax, in currency.
tax*numberThe tax, in currency.
total*numberThe amount charged, in currency.
customer_ip_address*|The IP address the payment was made from.
customer_ip_country*|The ISO 3166-1 alpha-2 country of customer_ip_address.
description*|Your description of the payment.
reference*|Your own reference for the payment. You can filter lists on it.
merchant_descriptor*|What appears on the shopper's card statement.
merchant_contact*|The contact shown with the statement descriptor, such as a phone number or web address.
apply_to_balance*booleanTrue when the captured total is added to the customer's store credit balance.
response_code?stringOK for a successful step, otherwise a code for why the payment failed. Not returned to a limited token.
response_message?stringA readable message for response_code. Not returned to a limited token.
gateway_transaction_id?|The gateway's own id for the transaction. Not returned to a limited token.
gateway_error_code?|The gateway's error code when the payment failed. Not returned to a limited token.
gateway_error_message?|The gateway's error message when the payment failed. Not returned to a limited token.
risk_decline?booleanTrue when the payment was declined for fraud risk. Not returned to a limited token.
gateway?|The URL of the gateway used, or the gateway with expand=gateway. Only for a token that may read gateways. Not returned to a limited token.
debug?stringOnly on accounts on the agent model. The URL of the raw gateway exchanges for this payment, for troubleshooting. Not returned to a limited token.
uriapp_id?|The hosted app the payment came from, if any. Not returned to a limited token.
app_version?|The version of that app. Not returned to a limited token.
payment_method*|The URL of the payment method used, or the method itself with expand=payment_method.
response_data*|The URL of the payment's response data, or the data itself with expand=response_data. This is where a redirect, a 3-D Secure step or the Stripe.js values for an initiated payment are.
reporting_currency*|Your account's reporting currency.
reporting_subtotal*numbersubtotal in reporting_currency.
reporting_shipping*numbershipping in reporting_currency.
reporting_tax*numbertax in reporting_currency.
reporting_total*numbertotal in reporting_currency.
reporting_fx_rate*numberThe rate from the settlement currency to reporting_currency.
reporting_alt_currency?stringYour second reporting currency. Only present when you set one.
reporting_alt_subtotal?numbersubtotal in reporting_alt_currency. Only present with a second reporting currency.
reporting_alt_shipping?numbershipping in reporting_alt_currency. Only present with a second reporting currency.
reporting_alt_tax?numbertax in reporting_alt_currency. Only present with a second reporting currency.
reporting_alt_total?numbertotal in reporting_alt_currency. Only present with a second reporting currency.
reporting_alt_fx_rate?numberThe rate to reporting_alt_currency. Only present with a second reporting currency.
settlement_currency?stringThe currency the payment settles to your account in. Not returned to a limited token.
settlement_subtotal?numbersubtotal in settlement_currency. Not returned to a limited token.
settlement_shipping?numbershipping in settlement_currency. Not returned to a limited token.
settlement_tax?numbertax in settlement_currency. Not returned to a limited token.
settlement_total?numbertotal in settlement_currency. Not returned to a limited token.
fx_rate?numberThe rate from currency to settlement_currency. Not returned to a limited token.
customer?|The URL of the customer, or the customer with expand=customer.
order?||The URL of the order the payment paid for, the order with expand=order, or null.
cart?||The URL of the cart the payment was for, the cart with expand=cart, or null.
invoice?||The URL of the invoice the payment was for, the invoice with expand=invoice, or null.
refunds?|The URL of the payment's refunds, or an offset list of them with expand=refunds (not inside a list).
fees?|The URL of the payment's fees, or an offset list of them with expand=fees (not inside a list). Not returned to a limited token.
fee_summary?|The URL of the payment's fee summary, or the summary with expand=fee_summary. Not returned to a limited token.
commissions?|The URL of the payment's commissions, or an offset list of them with expand=commissions (not inside a list). Not returned to a limited token.
failed_gateway_attempts?|The URL of the gateways that declined before this one took the payment. For staff troubleshooting. Not returned to a limited token.
meta*||Your own data for the payment, a string or an object.
formatted?Money amounts and dates as display strings. Only present with formatted=true.
curl -X POST 'https://api.comecero.com/api/v1/payments' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "name": "John Smith", "email": "john@example.com", "billing_address": { "address_1": "1 Main St", "city": "High Point", "state_prov": "NC", "postal_code": "27265", "country": "US" } }, "payment_method": { "type": "credit_card", "data": { "number": "4444555566661111", "exp_month": 12, "exp_year": 2030, "cvv": "123", "cardholder_name": "John Smith" } }}'{ "object": "payment", "url": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC", "payment_id": "0090460891496PyrYzd9DC", "account_id": "AB1234", "success": true, "status": "completed", "date_created": "2026-11-07T19:25:02Z", "date_modified": "2026-11-07T19:25:04Z", "date_completed": "2026-11-07T19:25:04Z", "test": true, "currency": "USD", "subtotal": 199.9, "shipping": 0, "tax": 14.99, "total": 214.89, "customer_ip_address": "203.0.113.44", "customer_ip_country": "US", "description": null, "reference": null, "merchant_descriptor": "EXAMPLE SHOP", "merchant_contact": "shop.example.com", "apply_to_balance": false, "response_code": "OK", "response_message": "OK", "gateway_transaction_id": "test_ch_1029384756", "gateway_error_code": null, "gateway_error_message": null, "risk_decline": false, "gateway": "https://api.comecero.com/api/v1/gateways/0090100200300GwTest01", "app_id": null, "app_version": null, "payment_method": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/payment_method", "response_data": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data", "reporting_currency": "USD", "reporting_subtotal": 199.9, "reporting_shipping": 0, "reporting_tax": 14.99, "reporting_total": 214.89, "reporting_fx_rate": 1, "settlement_currency": "USD", "settlement_subtotal": 199.9, "settlement_shipping": 0, "settlement_tax": 14.99, "settlement_total": 214.89, "fx_rate": 1, "customer": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1", "order": "https://api.comecero.com/api/v1/orders/8352-CSGYX-348", "cart": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1", "invoice": null, "refunds": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/refunds", "fees": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fees", "fee_summary": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fee_summary", "commissions": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/commissions", "failed_gateway_attempts": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/failed_gateway_attempts", "meta": null}List all payments GET
Lists the payments of your account, failed ones included. A cursor-based list: page with `after_item` and `before_item`. It has no `sort_by`. Secret and trusted tokens only; a limited token gets `403`. Inside the list, `refunds`, `fees`, `commissions` and `failed_gateway_attempts` are always URLs.
Retrieve payment options GET
Returns what a shopper can pay with on your account for a payment with no cart or invoice: your currencies, the best currency for the caller's location, the payment methods and card types in a currency, and the customer fields to collect. For a cart, use `GET /carts/{cart_id}/options` instead. Any token type may call it.