Payments API Concepts

The Payments API enables partners to act as payment gateway providers — participating in real-time transaction authorization by responding to webhook events. Unlike payment currencies (where mCards evaluates balances directly), payment gateways give the partner active control over authorization decisions.

Payment Gateways

A payment gateway represents a partner's payment processing capability on the mCards platform. Each gateway:

Has a unique identifier (payment_gateway_uuid)
Has a status (active or inactive)
Is associated with one or more distributor cards (card programs)
May have an operations account for settlement tracking
May provide an onboarding URL for cardholder enrollment

Payment Accounts

A payment account links a specific cardholder card to a payment gateway. Payment accounts are created when cardholders enroll with a payment provider and represent the relationship between:

The cardholder's card
The partner's payment gateway
The cardholder's account with the payment provider

Payment accounts have:

Property	Description
Status	`active`, `inactive`, or other lifecycle states
Available balance	Funds available for authorization (maintained by the partner)
Current balance	Total account balance

Authorization Flow

When a cardholder makes a purchase, the Dynamic Processing Engine (DPE) evaluates payment accounts in rank order. For payment gateway accounts, the flow is:

Authorization request — mCards receives the request from the card network
DPE evaluation — The DPE identifies the payment gateway account and sends an authorization webhook to the partner
Partner decision — The partner receives the webhook and responds with an approval or decline
Transaction completion — mCards relays the decision to the card network

Webhook Event Types

Payment gateway authorization uses several webhook event types:

Event	Description
`payment.hold`	Authorization hold — partner should reserve funds
`payment.capture`	Capture — partner should finalize the transaction
`payment.release_hold`	Release — partner should release a previous hold
`payment.hold_and_capture`	Combined hold and capture in a single message
`payment.get_balance`	Balance inquiry — partner should return current balance

See Webhooks API Concepts for delivery details and signature verification.

Comparison: Payment Gateways vs Payment Currencies

	Payment Gateways (Payments API)	Payment Currencies (Currency API)
Partner role	Active — approves or declines via webhook	Passive — provides balance data only
Real-time decisioning	Yes — partner responds to each authorization	No — mCards evaluates balance directly
Webhook involvement	Required — `payment.*` events	None during authorization
Use case	Partner-controlled payment processing	Balance-based value (loyalty, rewards as payment)

DPE Rank Order and Payment Gateways

When a cardholder's card has multiple payment accounts, the DPE evaluates them in rank order. For payment gateway accounts, this means:

The DPE reaches the gateway's payment account in the rank sequence
An authorization webhook (payment.hold) is sent to the gateway partner
The partner evaluates the request and responds with approve or decline
If declined, the DPE moves to the next payment account in rank order

A single cardholder card may have payment accounts from multiple gateways and/or currencies. The rank order determines which is tried first, second, etc. See Platform Integration Concepts for the full DPE evaluation flow.

Syndicated Distributor Cards

Payment gateways are linked to distributor cards (card programs) through syndication. A gateway's payment_gateway_syndicated_distributor_cards field lists the card programs that can use this gateway for authorization.

Syndication determines:

Which cardholders can use the gateway — Only cardholders with cards issued under a syndicated card program have payment accounts with the gateway
Rank order — The gateway's position in the DPE evaluation sequence for each syndicated card program
Scope of access — A gateway may be syndicated to one card program or many, depending on the business relationship

Operations Accounts

Each payment gateway may have an associated operations account used for:

Settlement tracking
Balance reconciliation
Financial integrity across the platform

Related Guides

Platform Integration Concepts — Transaction lifecycle and the DPE
Currency API Concepts — Balance-based payment currencies
Webhooks API Concepts — Webhook delivery, security, and event types
API Authentication and Credentials — Authenticating API requests
Payment API Reference — Full endpoint documentation