M2P Fintech API documentation

Status Values

Click to Pay tracks status at three levels: entity (customer), kit (card), and request.

Entity & Kit Status

Both entities and kits share the same set of CTP status values:

Status	Description
`UNREGISTERED`	Not enrolled in Click to Pay
`REGISTRATION_IN_PROGRESS`	CTP enrollment request sent to Visa, awaiting confirmation
`ACTIVE`	Successfully registered and active on the Visa CTP network
`REMOVAL_IN_PROGRESS`	CTP removal request sent to Visa, awaiting confirmation
`REMOVED`	Successfully removed from the Click to Pay network
`DISABLED`	Disabled on the CTP network

Request Trace Status

Each async CTP operation generates a request trace that tracks processing status:

Status	Description
`IN_PROGRESS`	Request submitted to Visa SaaS, awaiting result
`SUCCESS`	Operation completed successfully
`FAILED`	Operation failed — check error details

State Transitions

Entity Lifecycle

Kit Lifecycle

Request Trace Lifecycle

Database Model

The CTP module uses three database tables to track enrollment state:

`ctp_customer`

Tracks the entity-level CTP enrollment:

Column	Type	Description
`pkey`	BIGINT (PK)	Auto-generated primary key
`entity_id`	VARCHAR	M2P entity identifier
`clickToPayCustomerId`	VARCHAR	Visa CTP consumer ID (set on webhook callback)
`ctp_entity_status`	VARCHAR (Enum)	Current CTP status — one of `CTPEntityKitStatus` values
`business_entity_fkey`	BIGINT (FK)	Foreign key to `business_entity` table (OneToOne)

`ctp_payment`

Tracks card-level CTP enrollment, linked to ctp_customer:

Column	Type	Description
`pkey`	BIGINT (PK)	Auto-generated primary key
`clickToPayPaymentInstumentId`	VARCHAR	Visa CTP payment instrument ID
`ctp_kit_status`	VARCHAR (Enum)	Current CTP status for this card
`ctcustomer_pkey`	BIGINT (FK)	Foreign key to `ctp_customer` (ManyToOne)
`kit_pkey`	BIGINT (FK)	Foreign key to `kit` table (OneToOne)

`ctp_requestIdTracking`

Tracks the status of async CTP operations:

Column	Type	Description
`pkey`	BIGINT (PK)	Auto-generated primary key
`request_trace_ID`	VARCHAR	SaaS-provided request trace ID
`entity_id`	VARCHAR	M2P entity identifier
`kit_number`	VARCHAR	Kit number
`event`	VARCHAR (Enum)	CTP event type
`status_ctp`	VARCHAR (Enum)	Request status — `IN_PROGRESS`, `SUCCESS`, or `FAILED`

Database Indexes

Index	Table	Column(s)
`idx_ctp_customer_business_entity_fkey`	`ctp_customer`	`business_entity_fkey`
`idx_ctp_payment_kit`	`ctp_payment`	`kit_pkey`
`idx_ctp_requestIdTracking`	`ctp_requestIdTracking`	`request_trace_ID`

Entity Relationships

Async Processing Flow

All CTP registration and removal operations follow an asynchronous processing model via a CTP SaaS intermediary layer that communicates with the Visa Token Service.

SaaS API Endpoints

The M2P platform communicates with the CTP SaaS layer using these internal endpoints:

SaaS Endpoint	HTTP Method	CTP Event
`/addCustomerAndPaymentInstrument`	POST	`CTP_REGISTER_ENTITY_AND_KIT`
`/addPaymentInstrument`	POST	`CTP_ADD_KIT`
`/removeCustomer`	POST	`CTP_REMOVE_ENTITY`
`/removePaymentInstrument`	POST	`CTP_REMOVE_KIT`
`/updateCustomerData`	PUT	`CTP_UPDATE_ENTITY`
`/updatePaymentInstrument`	PUT	`CTP_UPDATE_KIT`
`/getData`	GET	Fetch entity details
`/status`	GET	Poll request status

SaaS API requests include an X-TENANT-ID header for tenant identification.

Automatic CTP Updates

The platform automatically syncs CTP data when customer profiles are updated:

Trigger	CTP Action	Event
Customer name, email, or contact updated	Sync to Visa via `/updateCustomerData`	`CTP_UPDATE_ENTITY`
Customer address updated	Sync to Visa via `/updatePaymentInstrument`	`CTP_UPDATE_KIT`

These updates are triggered via Spring @TransactionalEventListener (AFTER_COMMIT), ensuring they only fire after the primary database transaction succeeds.

Notifications

All CTP operations generate notifications sent to the m2p.notification.all Message Queue queue:

Success Notification Payload

{
    "business": "ENBDTABBY",
    "transactionType": "CTP_REGISTER_ENTITY_AND_KIT",
    "serverNotifyData": {
        "entityId": "70752df2-...",
        "kitNo": "100000011561",
        "requestTraceId": "351562ba-...",
        "requestStatus": "SUCCESS",
        "transactionType": "CTP_REGISTER_ENTITY_AND_KIT",
        "ctpEntityStatus": "ACTIVE",
        "ctpKitStatus": "ACTIVE",
        "ctpEntityId": "86e9d8c0-...",
        "ctpKitId": "86e9d8c0-...",
        "tenant": "ENBDTABBY"
    }
}

Failure Notification Payload

{
    "business": "ENBDTABBY",
    "transactionType": "CTP_REGISTER_ENTITY_AND_KIT",
    "serverNotifyData": {
        "entityId": "70752df2-...",
        "requestTraceId": "351562ba-...",
        "requestStatus": "FAILED",
        "transactionType": "CTP_REGISTER_ENTITY_AND_KIT",
        "message": "CTP FAILURE: Request Rejected",
        "errorDetails": "...",
        "tenant": "ENBDTABBY"
    }
}

Lifecycle & Status