For the complete documentation index, see llms.txt. This page is also available as Markdown.

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_code determines 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 , wallet etc.

  • Storage: The save_payment_method field indicates the method stored safely for future use.

Identifiers at a glance

Identifier
Example
Who creates it
Where you use it

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?