Key Concepts
Before integrating with the recurring payment product, it is essential to understand the core entities involved in the payment flow. These concepts form the foundation of our API and are referenced throughout this documentation.
Payment Types:
Customer-Initiated Transaction (CIT): The shopper is present and actively authorizes the charge (e.g., a manual top-up).
Merchant-Initiated Transaction (MIT): The merchant processes the charge automatically (e.g., a monthly subscription fee).
Shoppers
A shopper represents the end-user who performs transactions using stored payment methods. In the context of recurring payments, a shopper acts as the root container for one or multiple linked payment methods.
Shopper Identification
Each shopper is uniquely identified by several attributes, including identifiers, status, and verified billing information.
{
"id": "shp_mcbis34tnsy8la6m19",
"created_at": "2024-02-17T10:00:00Z",
"finalized_at": "2024-02-17T10:30:00Z",
"status_code": "enabled",
"partner_shopper_id": "user001",
"email": "user001@example.com",
"phone_number": "+1234567890",
"zip_code": "10001",
"billing_first_name": "John",
"billing_last_name": "Doe",
"billing_document_type": "passport",
"billing_document_id": "A12345678",
"billing_country": "US",
"billing_address": "123 Payment St.",
"billing_region": "New York",
"billing_city": "New York"
}Why it matters:
Data Retrieval: Shopper IDs are required to fetch stored payment methods for recurring transactions.
Flexibility: A single shopper can maintain multiple saved payment methods across different providers.
Eligibility: The
status_codedetermines if the shopper is currently eligible for payment processing.Compliance: Detailed billing information may be required for document verification or regional regulatory requirements.
Payment Methods
A payment method is the specific financial instrument (e.g., a credit card) used for transactions. Note that while our system supports various types, recurring features are currently limited to cards.
Payment Method Identification
Each method is identified by its type and its specific support for different transaction flows.
Why it matters:
Multi-method Support: Shoppers can save various cards and wallets to their profiles. Each payment method belongs to unique payment method type e.g.
card,walletetc.Storage: The
save_payment_methodfield indicates the method stored safely for future use.
Identifiers at a glance
partnerShopperId
user-105
You
Every Init for this user (case-sensitive, must stay the same)
Shopper id
shp_sg1a...
Coda
Optional in later Init (shopper.id) to look up the shopper
Payment method id
pmt_sg1a...
Coda
paymentMethodId in Token Charge
txnId
7936048693099035406
Coda
Inquiry, reconciliation, support tickets
orderId
1793604868432
You
Unique per Init and per Token Charge
Note: The objects above show Coda's internal field names (snake_case). Webhook payloads use camelCase (for example
shopper.partnerShopperId). Always parse webhooks using the field names shown on the webhook pages.
Note: If the same shopper saves the same card again, Coda returns the same
paymentMethod.id. It does not create a duplicate token.
Last updated
Was this helpful?