Transaction authorizations
Understand the real-time authorization process that occurs at the point of sale. This guide explains how we approve or decline transaction requests based on card status, spending controls, and available funds.
Card Authorization Process
User, Card, and Account Validation
Before the transaction authorization process can happen, the MatchMove system checks the following:
- The account is
activeand not in therisk_flaggedstate - The card is in
activestate
Failure to meet any of these conditions will cause the transaction to be rejected.
Transaction Controls
The system will also check if the transaction:
- is from a card linked to an active card program
- is from a card that is associated with a valid cardholder, who has either in a
pre_kycor apost_kycstatus.
Failure to meet any of these conditions will cause the transaction from being created.
Card Controls
The system will also check if the transaction:
- amount requested for authorization meets the requirements and controls in terms of spending velocity.
- amount requested for authorization meets the criteria defined for card controls
- amount requested for authorization meets the criteria defined in the user-level configurations
Pre-authorization Flow
If the partner is on a shared authorization model, then the payment request is forwarded to the partner at the point of authorization. Partners must then provide a decision on the transaction within an agreed-upon time frame. Otherwise, the transaction will be automatically declined.
Transaction Entry Posting
This event will happen when a transaction record is created corresponding to a transaction authorization object and added to the card-associated account in relation to the program funding model configured for the platform.
Transaction Reversals
This event will happen when a transaction that is previously authorized by the system gets rejected by the merchant. Transaction rejection can be due to a variety of reasons, such as in-store refunds, order cancellations, etc. The transaction will be reversed in the system, and the funds will be returned to the cardholder's account.
Funding Models
The high-level process remains the same across various account funding models supported in the platform. The differences between various funding models when performing a financial transaction are highlighted below:
Balance check will be done on.. | Account balance | Card account balance | Program pre-fund account |
Transaction posting will be done on.. | Account balance | Card account balance | Program pre-fund account Real-time credit and debit on account balance |
Authorization Models
The MatchMove platform allows partners to decide on how the authorization process will proceed in the program. Two(2) authorization models are available and applicable to all financial and non-financial transactions:
- Platform-managed - where the MatchMove platform controls the end-to-end process of card authorization
- Shared authorization - where the partner decides on a segment of the authorization process.
The table below highlights the key differences between platform-managed authorization and shared authorization:
Customer Authentication (for Card-not-present transactions) | Managed by the platform | Managed by the platform |
Customer account status check | Managed by the platform | Managed by the platform |
Card status and rules check | Managed by the platform | Managed by the platform |
Merchant blacklist check | Managed by the platform | Managed by the platform |
Transaction type eligibility check | Managed by the platform | Managed by the platform |
Fees computation and charge | Managed by the platform | Managed by the platform |
Token eligibility check | Managed by the platform | Managed by the platform |
Program Card velocity and controls check | Managed by the platform | Managed by the platform |
User-level card velocity and controls check | Managed by the platform | Managed by the platform |
Decision to approve the transaction | Managed by the platform | Managed by the partner |
Transaction records creation | Managed by the platform | Managed by the platform/partners to define the behavior in the partner's system |
Clearing and settlement | Managed by the platform | Managed by the platform/partners to define the behavior in the partner's system |
End customer notification (if needed) | Managed by the partner | Managed by the partner |
Platform-managed Authorization
In platform-managed authorization, the MatchMove platform manages the entire card transaction lifecycle. This includes, but is not limited to, the posting of the transactions, adjusting based on settlements, and evaluating business rules as configured in the platform.
Webhook Integration
Integrating webhooks for the platform-managed authorization is not required. But partners may want to add these webhooks if they want to provide a better transaction experience to the end-users or if the program use-case warrants it.
Non-financial Transaction Webhooks
Non-financial Transaction Webhooks
The non-financial transactions currently supported by the system are Account Status Inquiries (ASI) transactions.
Account Verification status webhook
Account verification is also known as “account status inquiry”. This transaction is used to verify the status of an account, including whether it is active, inactive, or has any restrictions.
It can be initiated by merchants during a transaction or by financial institutions for administrative purposes. This is primarily used by merchants who want to confirm if the cardholder’s account is active and in good standing before completing a transaction. It aims to reduce the risk of declined transactions and potential fraud for a card-not-present transaction.
CARDS.ACCOUNT_VERIFICATION.STATUS | A message containing the verified customer status |
Sample Account Verification Status webhook payload
{
"entities": {
"account": {
"balance": {
"available": {
"balance": "0.00",
"currency": "PHP"
}
},
"balance_type": "Shared Balance",
"id": "368ea2999b9b6a6f129951019e89a325"
},
"card": {
"id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2",
"type": "{{card_type_code}}"
},
"transaction": {
"channel": "ECOM",
"created_at": "2025-11-12T22:04:51+08:00",
"id": "AV_8e1176affb9c43c89636b855524b6795",
"local_transaction_date": "11-12",
"local_transaction_time": "",
"merchant_details": {
"acquiring_country_code": "840",
"acquiring_institution": "015611",
"institution_code": "015611",
"merchant_category_code": "5969",
"merchant_id": "CARD ACCPT IDC ",
"merchant_name": "Agoda St. Louis USA",
"terminal_id": ""
},
"network": "MASTER",
"reason": "OK",
"transaction_amount": "0.00",
"transaction_currency": "PHP",
"transaction_type": "Account Verification"
},
"user": {
"email": "*****es8@gmail.com",
"id": "b32dced37aed454ebe6379cbb39984f8",
"mobile": "9064003872",
"mobile_country_code": "63"
}
},
"entity_id": "AV_8e1176affb9c43c89636b855524b6795",
"entity_type": "TRANSACTIONS",
"event_timestamp": "2025-11-12T14:04:51Z",
"message_id": "01cd517169214b74b9ec06f3456b51a1",
"program_code": "{{program_code}}",
"version": "v2",
"webhook_event": "CARDS.ACCOUNT_VERIFICATION.STATUS"
}Financial Transaction Webhooks
Financial Transaction Webhooks
Declined Transaction Notification webhooks
This webhook event is triggered every time a transaction is declined by the MatchMove platform due to various reasons and errors in the authorization.
Please note that MatchMove is a distributed system which interacts with various services. If the decline happens from within or is captured in the system, these decline notifications will be sent.
However, for declines that are caught on interfacing services, these notifications are not guaranteed to be sent.
But it is important for partners to subscribe to these webhooks to be informed of transaction declines happening in the program and to be able to handle them when they are received.
The webhook has a payload that contains the details of the transaction and the reason for decline.
OPENLOOP_DECLINED_INVALID_TRANSACTION | Declined transaction message sent to API consumer |
OPENLOOP_DECLINED_INSUFFICIENT_CONSUMER_BALANCE | Declined transaction message sent to API consumer when there is not enough consumer balance to fulfill the transaction (Only applicable for JIT programs where the amount is fulfilled from the prefund) |
OPENLOOP_DECLINED_INSUFFICIENT_BALANCE | Declined transaction message sent to the API consumer when the cardholder's balance is not enough to fulfill the transaction. |
OPENLOOP_DECLINED_INSUFFICIENT_CATEGORY_BALANCE | Declined transaction message sent to API consumer when the category balance is not enough to fulfill the transaction for that category-specific transaction (Only applicable if the fund categories feature is being used) |
OPENLOOP_DECLINED_CATEGORY_LIMIT_REACHED | Declined transaction message sent to the API consumer when the limit for the transaction category is reached. (Only applicable if the fund categories feature is being used) |
OPENLOOP_DECLINED_CARD_BLOCKED | Declined transaction message sent to the API consumer when an authorization request is received for a blocked card |
OPENLOOP_DECLINED_CARD_SUSPENDED | Declined transaction message sent to the API consumer when an authorization request is received for a suspended card |
OPENLOOP_DECLINED_INVALID_TRANSACTIONTYPE | Declined transaction message sent to the API consumer when a transaction type not supported by the card type is received for authorization |
OPENLOOP_DECLINED_UNSUPPORTED_PROGRAM_MERCHANTS | Declined transaction message sent to API consumer if request comes for a merchant that is blacklisted on the program/card_type |
OPENLOOP_DECLINED_RISKCHECKFAILED | Declined transaction message sent to the API consumer when the velocity limits configured are breached. |
OPENLOOP_DECLINED_ALREADY_AUTHORIZED_TRANSACTION | Declined transaction message sent to the API consumer when we receive a duplicate authorization request for a transaction already authorized. The probability of this error message being triggered is very remote |
OPENLOOP_DECLINED_REFRENCE_NOT_FOUND | Declined transaction message sent to API consumer |
OPENLOOP_DECLINED_AGGREGATE_LIMIT_REACHED | Declined transaction message sent to API consumer when the aggregate limit for the user against the bin sponsor is reached (Only applicable if the specific program has a BIN sponsor level limit cap) |
OPENLOOP_DECLINED_USER_SUSPENDED | Declined transaction message sent to the API consumer when the user is suspended |
OPENLOOP_DECLINED_USER_BLOCKED | Declined transaction message sent to the API consumer when the user is blocked |
OPENLOOP_DECLINED_USER_NOT_FOUND | Declined transaction message sent to the API consumer when the user is not found |
OPENLOOP_DECLINED_UNSUPPORTED_ACQUIRING_MERCHANT_COUNTRY | Declined transaction message sent to the API consumer when the acquiring country is not supported by the BIN sponsor |
OPENLOOP_DECLINED_UNSUPPORTED_TRANSACTION_CURRENCY | Declined transaction message sent to the API consumer when the transaction currency is not supported by the bin sponsor |
OPENLOOP_DECLINED_USERS_LIMITS_BREACHED | Declined transaction message sent to the API consumer when the user's limit is breached |
OPENLOOP_DECLINED_PROGRAM_LIMITS_BREACHED | Declined transaction message sent to the API consumer when the program's limit is breached |
OPENLOOP_DECLINED_PROGRAM_ATM_DOMESTIC_LIMITS_BREACHED | Declined transaction message sent to API consumer when ATM_DOMESTIC is not enabled at the program level |
OPENLOOP_DECLINED_PROGRAM_POS_LIMITS_BREACHED | Declined transaction message sent to the API consumer when POS is not enabled at the program level |
OPENLOOP_DECLINED_PROGRAM_POS_CONTACTLESS_LIMITS_BREACHED | Declined transaction message sent to API consumer when POS_CONTACTLESS is not enabled at the program level |
OPENLOOP_DECLINED_PROGRAM_ECOM_LIMITS_BREACHED | Declined transaction message sent to the API consumer when ECOM is not enabled at the program level |
OPENLOOP_DECLINED_PROGRAM_ATM_LIMITS_BREACHED | Declined transaction message sent to the API consumer when the ATM is not enabled at the program level |
OPENLOOP_DECLINED_USERS_ATM_DOMESTIC_LIMITS_BREACHED | Declined transaction message sent to API consumer when ATM_DOMESTIC is not enabled at the user level |
OPENLOOP_DECLINED_USERS_POS_CONTACTLESS_LIMITS_BREACHED | Declined transaction message sent to API consumer when POS_CONTACTLESS is not enabled at the user level |
OPENLOOP_DECLINED_USERS_POS_LIMITS_BREACHED | Declined transaction message sent to the API consumer when the POS is not enabled at the user level |
OPENLOOP_DECLINED_USERS_ECOM_LIMITS_BREACHED | Declined transaction message sent to API consumer when ECOM is not enabled at user level |
OPENLOOP_DECLINED_CARD_PENDING_ACTIVATION | Declined transaction message sent to the API consumer when an authorization request is received for a pending activation card |
OPENLOOP_DECLINED_OFACCHECKFAILED | Declined transaction message sent to the API consumer when the user's OFAC status fails |
Successful Transaction Notifications webhook
This webhook event is triggered every time a transaction is successfully authorized by the MatchMove platform.
It will be vital for partners to subscribe to this webhook, so they can be informed of every successful transactions happening in the program.
This webhook payload is also important as it contains details of the authorized transaction. The webhook payload will be the source of the data for the completed transaction notification that can be forwarded to the customers through various channels.
OPENLOOP_POST_AUTH | A successful transaction message containing the transaction details |
Open Loop Reversal webhooks
Even though transactions are already authorized, there will still be a chance that this transaction gets reversed. The reasons for reversal can be due to various reasons initiated by the cardholder, merchant, or the network. The reversal proceedings will be fully managed by the platform, including the return of funds to the cardholder accounts.
This webhook payload also contains the details of the transaction and the reason for reversal. These details can also be forwarded to the end-users through various channels.
OPENLOOP_TRANSACTION_REVERSAL | A reversal transaction message is sent to the API consumer when a transaction that has already been authorized is reversed |
OPENLOOP_REVERSAL_CATEGORY_LIMIT_REACHED | Reversal transaction message sent to the API consumer |
Shared Authorization
In shared authorization, partners can choose to participate in the card transaction authorization process, where they provide an authorization decision. This decision may be based on the result of a custom business logic. Providing this decision can override the default platform outcome for the specific transaction.
The shared authorization can be enabled by subscribing to the pre-authorization webhook. Subscribing to this webhook is a contract that gives partners the responsibility to respond with an “authorize or not authorize” decision within an allotted time frame. Failure to respond to this webhook will automatically decline the transaction request.
Timeout limit for pre-auth webhook
For compliance with the card network SLA, the partners are expected to respond to the webhook before the timeout limit of 3 seconds.
Failure to respond to this webhook will automatically decline the transaction request.
Non-financial Transactions Webhooks
Non-financial Transactions Webhooks
Account status authorization pre-auth webhook
This webhook is triggered every time an account verification request is received. Subscribed partners can then opt to allow or decline the request.
CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION | Pre-auth webhook message sent to a subscribed partner, who wants to approve/decline an account verification request |
Sample Account Verification webhook payload
{
"entities": {
"account": {
"balance": {
"available": {
"balance": "0.00",
"currency": "PHP"
}
},
"balance_type": "Shared Balance",
"id": "368ea2999b9b6a6f129951019e89a325"
},
"card": {
"id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2",
"type": "{{card_type}}"
},
"transaction": {
"channel": "ECOM",
"created_at": "2025-11-12T22:04:51+08:00",
"id": "AV_8e1176affb9c43c89636b855524b6795",
"local_transaction_date": "11-12",
"local_transaction_time": "",
"merchant_details": {
"acquiring_country_code": "840",
"acquiring_institution": "015611",
"institution_code": "015611",
"merchant_category_code": "5969",
"merchant_id": "CARD ACCPT IDC ",
"merchant_name": "Agoda St. Louis USA",
"terminal_id": ""
},
"network": "MASTER",
"transaction_amount": "0.00",
"transaction_currency": "PHP",
"transaction_type": "Account Verification"
},
"user": {
"email": "****@gmail.com",
"id": "b32dced37aed454ebe6379cbb39984f8",
"mobile": "9064003872",
"mobile_country_code": "63"
}
},
"entity_id": "AV_8e1176affb9c43c89636b855524b6795",
"entity_type": "TRANSACTIONS",
"event_timestamp": "2025-11-12T14:04:51Z",
"message_id": "2d744b1881c14bac8ecc15a77a13340a",
"program_code": "{{program_code}}",
"version": "v2",
"webhook_event": "CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION"
}Partners can allow the verification request to proceed by responding by responding with:
{
"action":"APPROVE",
}Partners can allow the verification request to proceed and forward an additional description to the approval by responding with:
{
"action":"APPROVE",
"description":"The action was approved by the system or any other message"
}Partners also can choose to reject the verification request and stop it from proceeding by responding with:
{
"action":"DECLINE",
"description":"System decline for reason code PARTNER-001 or any other message"
}Aside from the normal verification requests, partners will also need to handle verification request statuses changes with the specific reason codes.
CARDS.ACCOUNT_VERIFICATION.STATUS | Message sent for verification request status changes |
Sample Account Verification Status webhook payload
{
"entities": {
"account": {
"balance": {
"available": {
"balance": "0.00",
"currency": "PHP"
}
},
"balance_type": "Shared Balance",
"id": "368ea2999b9b6a6f129951019e89a325"
},
"card": {
"id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2",
"type": "{{card_type_code}}"
},
"transaction": {
"channel": "ECOM",
"created_at": "2025-11-12T22:04:51+08:00",
"id": "AV_8e1176affb9c43c89636b855524b6795",
"local_transaction_date": "11-12",
"local_transaction_time": "",
"merchant_details": {
"acquiring_country_code": "840",
"acquiring_institution": "015611",
"institution_code": "015611",
"merchant_category_code": "5969",
"merchant_id": "CARD ACCPT IDC ",
"merchant_name": "Agoda St. Louis USA",
"terminal_id": ""
},
"network": "MASTER",
"reason": "OK",
"transaction_amount": "0.00",
"transaction_currency": "PHP",
"transaction_type": "Account Verification"
},
"user": {
"email": "*****es8@gmail.com",
"id": "b32dced37aed454ebe6379cbb39984f8",
"mobile": "9064003872",
"mobile_country_code": "63"
}
},
"entity_id": "AV_8e1176affb9c43c89636b855524b6795",
"entity_type": "TRANSACTIONS",
"event_timestamp": "2025-11-12T14:04:51Z",
"message_id": "01cd517169214b74b9ec06f3456b51a1",
"program_code": "{{program_code}}",
"version": "v2",
"webhook_event": "CARDS.ACCOUNT_VERIFICATION.STATUS"
}DECLINED_BY_PARTNER | Authorization request either declined by the Partner or an invalid response received from Partner |
TIMEOUT_BY_PARTNER | Declined transaction message sent to API consumer due to time out or no response received from Partner within SLA |
CLIENT_SERVER_ERROR | Declined transaction due to connectivity issues between Client server and MatchMove platform typically caused by network problems or server unavailability |
Financial Transaction Webhooks
Financial Transaction Webhooks
Pre-auth webhooks
This webhook is triggered every time a transaction authorization request is received and the partner is subscribed to the webhook.
The category for this webhook event is Pre Auth
OPENLOOP_PRE_AUTH | Pre-auth message sent to a subscribed API consumer when a transaction authorization request is received by the system |
Authorize the transaction
Partners can approve the transaction authorization request by responding with:
{
"status":"OK",
"description":"Authorization OK"
}Partners can decline the transaction authorization request by responding with:
{
"status":"UNAUTHORIZED",
"description":"Unauthorized"
}Address and handle failures
If the partner were unable to respond to the stipulated response SLA, the transaction will be automatically declined.
However, there will be a chance that the partner system might have already authorized the transaction. But the webhook response were not able to make it in time before the response SLA expired.
To help ensure the real-time correction of records in these types of scenarios, the MatchMove platform will trigger an auto-reversal advisory message informing of the failure/decline of the transaction with the relevant reasons.
OPENLOOP_TRANSACTION_REVERSAL | This is the advisory message sent when the Pre-Auth webhook was sent, but the system is unable to receive the response message from the partner. This results in an automatic decline of the transaction authorization request. |
Partners receiving this reversal advisory message are encouraged to do real-time corrective actions (if needed) on their ledger or system, which has been previously authorized on their side.
Related Links
On this page
- Transaction authorizations