comecerodocs
Settings

Update payment settings

POST
/settings/payment

Changes the payment settings. Send only the fields you want to change. allow_save_cards is set by Comecero and ignored if you send it. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include settings_payment. Limited tokens may not.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Query Parameters

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When 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.

Defaultfalse

Request Body

application/json
  1. body

The payment fields to change. Send only the fields you want to change. Lists you send replace the saved list.

Properties1 <= properties
merchant_descriptor_name?|

The name on the card statement. Up to 18 characters.

Lengthlength <= 18
product_as_merchant_descriptor_name?boolean

Use the first product name on the card statement.

merchant_descriptor_contact?|

A phone number, web address or city on the statement. Up to 11 characters.

Lengthlength <= 11
save_cards_by_default?boolean

Save the card when a payment does not say. Ignored unless allow_save_cards is true on the account.

ignore_bad_cvv?boolean

Let a payment succeed when the CVV does not match.

ignore_bad_avs?boolean

Let a payment succeed when the address check does not match.

duplicate_payment_timeout?integer

Seconds during which an exact repeat payment is refused. 0 turns it off.

Range0 <= value <= 600
default_payment_currency?string

ISO 4217 currency code.

default_settlement_currency?string

ISO 4217 currency code.

currency_settlement_rules?array<>|

The full list of settlement rules. null clears them.

customer_required_fields?array<>

Customer fields a shopper must fill in. Repeats are removed.

customer_optional_fields?array<>

Customer fields offered but not required. Must not overlap the required list.

refund_reasons?array<string>

The reasons offered for a refund.

chargeback_reasons?array<string>

The reasons offered for a chargeback.

blocked_countries?array<string>

Two-letter ISO country codes to refuse. Up to 50.

Itemsitems <= 50
max_gateway_attempts?|

When a card is declined and more than one gateway can take it, how many gateways to try in total. A value below 1, or null, means no limit: every gateway that can take the payment is tried. New accounts start at 2.

Response Body

The payment settings, after the change.

application/json
  1. response

How the account takes payments in the current mode: card statement text, saved cards, currencies, duplicate and country checks, and the reasons offered for refunds and chargebacks.

object?"settings_payment"

The object type. Always settings_payment.

Value in"settings_payment"
url?string

The URL of this object.

Formaturi
account_id?string

The ID of the account the settings belong to.

test?boolean

True for the test mode settings, false for live.

date_created?string

When the settings were created.

Formatdate-time
date_modified?string

When the settings were last changed.

Formatdate-time
merchant_descriptor_name?|

The name on the customer's card statement. Card networks show up to 18 characters. null uses your company name.

Lengthlength <= 18
product_as_merchant_descriptor_name?boolean

For a cart payment, use the name of the first product as the statement name instead of merchant_descriptor_name.

merchant_descriptor_contact?|

A phone number, web address or city on the card statement. Up to 11 characters.

Lengthlength <= 11
allow_save_cards?boolean

Whether this account may save cards on customers for later one-time payments. Set by Comecero: a value you send is ignored.

save_cards_by_default?boolean

Save the card on the customer when a payment does not say. Only changes when allow_save_cards is true.

ignore_bad_cvv?boolean

Let a card payment succeed even when the CVV does not match.

ignore_bad_avs?boolean

Let a card payment succeed even when the address check (AVS) does not match. Address checks are not enforced on the platform at present, so this has no effect today.

duplicate_payment_timeout?integer

Seconds during which an exact repeat of a payment request is refused. From 0 to 600. 0 turns the check off (not recommended).

Range0 <= value <= 600
default_payment_currency?string

The currency (ISO 4217) used when a payment does not name one.

default_settlement_currency?string

The currency (ISO 4217) payments settle in when no settlement rule matches.

currency_settlement_rules?array<>

Which currency each payment currency settles in.

customer_required_fields?array<>

Customer fields a shopper must fill in at checkout.

customer_optional_fields?array<>

Customer fields offered at checkout but not required. A field cannot be in both lists.

refund_reasons?array<string>

The reasons offered when someone issues a refund.

chargeback_reasons?array<string>

The reasons offered when someone records a chargeback.

blocked_countries?array<string>

Two-letter ISO country codes payments are refused from. Up to 50.

Itemsitems <= 50
max_gateway_attempts?|

When a card is declined and more than one gateway can take it, how many gateways to try in total. null means no limit: every gateway that can take the payment is tried. New accounts start at 2.

Range1 <= value
formatted?

Display text for the dates. Returned only when formatted=true.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/settings/payment' \  -H 'Content-Type: application/json' \  -d '{  "merchant_descriptor_name": "EXAMPLE STORE",  "duplicate_payment_timeout": 120,  "customer_required_fields": [    "name",    "email",    "country"  ]}'
Example Response
{  "object": "settings_payment",  "url": "https://api.comecero.com/api/v1/settings/payment",  "account_id": "AB1234",  "test": true,  "date_created": "2026-01-12T09:30:00Z",  "date_modified": "2026-10-02T14:21:07Z",  "merchant_descriptor_name": "EXAMPLE STORE",  "product_as_merchant_descriptor_name": true,  "merchant_descriptor_contact": "8005551234",  "allow_save_cards": true,  "save_cards_by_default": false,  "ignore_bad_cvv": true,  "ignore_bad_avs": true,  "duplicate_payment_timeout": 120,  "default_payment_currency": "USD",  "default_settlement_currency": "USD",  "currency_settlement_rules": [],  "customer_required_fields": [    "name",    "email",    "country"  ],  "customer_optional_fields": [    "phone"  ],  "refund_reasons": [    "Customer request",    "Duplicate order"  ],  "chargeback_reasons": [    "Fraudulent Charge",    "Merchandise Not Received",    "Other"  ],  "blocked_countries": [],  "max_gateway_attempts": 2}

Get payment settings GET

Returns how the account takes payments: card statement text, saved cards, currencies, duplicate and country checks, and refund and chargeback reasons. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_payment`. Limited tokens may not.

Get pricing settings GET

Returns the exchange rate markups and rounding rules used when a price is converted into another currency. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_pricing`. Limited tokens may not.