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.

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": 123456,
  "created_at": "2024-02-17T10:00:00Z",
  "created_by": "system",
  "entity_id": "abc123",
  "owned_by": "merchant_789",
  "status_code": "ACTIVE",
  "email": "[e-mail]",
  "partner_shopper_id": "partner_001",
  "phone_number": "[phone]",
  "finalized_at": "2024-02-17T10:30:00Z",
  "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.

{
  "id": 987654,
  "created_at": "2024-02-17T10:00:00Z",
  "created_by": "system",
  "entity_id": "pm_abc123",
  "owned_by": "merchant_789",
  "shopper_id": "shopper_123",
  "type": "GoPay",
  "supports_tokenization": true,
  "supports_UIP": true,
  "supports_MIP": false
}

Why it matters:

• Multi-method Support: Shoppers can save various cards and wallets to their profiles.

• Transaction Logic: supports_UIP indicates if the method allows one-time, user-authorized transactions.

• Recurring Logic: supports_MIP indicates if the method allows automated, merchant-initiated billing.

• Storage: The supports_tokenization field dictates whether the method can be safely stored for future use.

Tokens

A token is a secure, unique reference to a shopper’s saved payment method. To ensure high security, sensitive payment details are replaced by a token ID for all subsequent transactions.

Token Usage Types:

• User-Initiated Payments (UIP): Tokens enable one-click checkouts, allowing shoppers to pay instantly without re-entering card details.

• Merchant-Initiated Payments (MIP): Tokens allow you to charge shoppers automatically for subscriptions or recurring bills.

Token Identification

{
  "id": 456789,
  "entity_id": "token_abc123",
  "owned_by": "merchant_789",
  "status": "ACTIVE",
  "payment_method_id": "pm_987654",
  "provider_id": "GoPay",
  "token": "secure_token_value",
  "token_type": "single_use",
  "token_details": {
    "masked_card_number": "**** **** **** 1234",
    "expiry_date": "12/26"
  },
  "is_default": true,
  "supports_UIP": true,
  "supports_MIP": false,
  "created_at": "2024-02-17T10:00:00Z",
  "created_by": "system",
  "updated_at": "2024-02-17T12:00:00Z"
}

Why it matters:

• Seamless UX: Tokens facilitate friction-free checkout experiences.

• Automation: They are the core mechanism for automated subscription billing.

• Permissioning: The supports_UIP and supports_MIP fields explicitly define how a specific token can be used in your payment flows.

Charges

A charge represents an individual payment request made against a saved payment method.

Charge Types:

• User-Initiated Payments (UIP): The shopper is present and actively authorizes the charge (e.g., a manual top-up).

• Merchant-Initiated Payments (MIP): The merchant processes the charge automatically (e.g., a monthly subscription fee).

Each charge is linked to a shopper, a tokenized payment method, and a specific amount/currency.

Charge Identification

{
  "id": 123456,
  "created_at": "2024-02-17T10:00:00Z",
  "created_by": "system",
  "entity_id": "charge_abc123",
  "owned_by": "merchant_789",
  "status_code": "PENDING",
  "amount_currency": "USD",
  "amount_value": 49.99,
  "item_code": "item_987654",
  "item_name": "Premium Subscription",
  "provider_reference": "txn_123456789",
  "subscription_id": "sub_56789",
  "token_id": "token_456789",
  "partner_reference": "partner_charge_001",
  "finalized_at": "2024-02-17T10:30:00Z",
  "partner_custom_data": {
    "custom_field_1": "value1",
    "custom_field_2": "value2"
  },
  "settings": {
    "retry_policy": "smart_retries",
    "capture_method": "automatic"
  },
  "shopper_agent": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0"
  },
  "provider_custom_data": {
    "additional_info": "provider-specific data"
  },
  "error_code": "NONE",
  "tax": {
    "vat": 2.50,
    "total_tax": 2.50
  }
}

Why it matters:

• Audit Trail: Charges track the lifecycle and outcome of every payment attempt.

• Error Handling: error_code values allow you to diagnose failures and trigger specific retry logic or customer notifications.