Add store credit by payment
Takes a payment from the customer and adds it to their store credit. This is the same as Create a payment: the body is a payment, and Comecero reads the customer from the body, not from the URL. To add the money to the balance, send apply_to_balance: true and the customer (customer_id or customer) in the body. The credit is added when the payment is captured, in the payment's currency converted to the balance currency.
The payment cannot use customer_account_balance as its payment method. Money moves and the usual payment events fire.
Secret tokens, and limited tokens. The id in the URL may be me only with a token from a customer login.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
customer_id*stringThe id of the customer. With a limited token from a customer login you can send me instead.
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/customers/string/balance/payments' \ -H 'Content-Type: application/json' \ -d '{ "customer_id": "0091304300408CuoxY9Pf3", "total": 25, "currency": "USD", "apply_to_balance": true, "payment_method": { "type": "credit_card", "data": { "number": "4444555566661111", "cvv": "123", "exp_month": 12, "exp_year": 2028, "cardholder_name": "John Doe" } }}'{ "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}Get a customer's balance GET
Gets a customer's store credit. The amount can be negative, for example after a refund paid to the balance was taken back. That is expected and is covered by the next credit. A customer who never had store credit has a balance of `0` in `USD`. Send `currency` to see the amount in another currency, converted at the account's exchange rate. Send `expand=transactions` to include the transactions. Secret tokens, and limited tokens tied to the customer.
List balance transactions GET
Lists every change to a customer's store credit, oldest first: credit added by refunds and top-up payments, and credit spent or taken back. Each transaction shows the balance right after it. The list is cursor-based: follow `next_page_url`, or send `after_item` or `before_item`. Filter by `date_start` and `date_end` (on `date_created`). Secret tokens, and limited tokens tied to the customer.