Using the synchronous webhook, you can approve or decline authorization requests in real time. When a card is used to make a purchase, Metaprise creates a card_authorization event and sends it to your configured endpoint for your approval.
Responding to authorization requests
Your endpoint must wait for a request from Metaprise for each approved or declined authorization request before responding to the incoming webhook response. If Metaprise does not receive your approval or decline your request within 1 second, the authorization is automatically declined.
Handling the authorization event
When the merchant makes purchases on the cards, an authorization request will send to your endpoint, the amount requested is stored in data with a pending status.
{
"event": "card_authorization",
"data": {
"id": "iauth_1MqVTNIrzgNAlS3T0OksBlGh",
"created":12412512,
"approved": false,
"card": "cd_20230222023605609701",
"amount": 2100,
"currency": "USD",
"merchant_data": {
"category": "mens_womens_clothing_stores",
"category_code": "5691",
"city": "NEW YORK",
"country": "US",
"name": "GOOGLE",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "pending"
}
}
Before closing the card_authorization event, you can approve or decline the authorization.
{
"event": "card_authorization",
"data":
{
"id":"iauth_1MqVTNIrzgN23S3T0OksBlGh",
"approved": true
}
}
If Metaprise receive your approval, and authorization create success. We will deduct the amount from your account balance, then send you a card_authorization webhook that set approved to true and status keep stay in pending, and create the pending transaction, send card_authorization event with a pending status.
{
"event": "card_authorization",
"data": {
"id": "iauth_1MqVTNIrzgNAlS3T0OksBlGh",
"created":12412512,
"approved": true,
"card": "cd_20230222023605609701",
"amount": 2100,
"currency": "USD",
"merchant_data": {
"category": "mens_womens_clothing_stores",
"category_code": "5691",
"city": "NEW YORK",
"country": "US",
"name": "GOOGLE",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "pending"
}
}
{
"event": "card_transaction",
"data": {
"id": "trn_0232452605609701",
"created": 12412512,
"card": "cd_20230222023605609701",
"amount": 2100,
"currency": "usd",
"merchant_data": {
"category": "computer_software_stores",
"category_code": "5734",
"city": "NEW YORK",
"country": "US",
"name": "GASGSAG",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "pending"
},
"sign": "123124124"
}
If you decline the authorization or the authorization is time-out after sending your response, the approved will keep in false and the status will be set to close, which means the authorization is closed, the amount will not deduct from your account balance, and the pending transaction will not create if you decline the authorization or authorization time-out.
{
"event": "card_authorization",
"data": {
"id": "evt_1LcgJbIrzgNAlS3Thx0Y8mqE",
"created":12412512,
"approved": false,
"card": "cd_20230222023605609701",
"amount": "2100",
"currency": "USD",
"merchant_data": {
"category": "mens_womens_clothing_stores",
"category_code": "5691",
"city": "NEW YORK",
"country": "US",
"name": "GOOGLE",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "closed"
}
}
Understanding the authorization event
When the merchant capture authorization, we will send you a card_authorization webhook with the true approved and the closed status which means the authorization was closed and will not update anymore. You will also receive a card_transaction webhook with the complete status that tells you the transaction is complete.
{
"event": "card_authorization",
"data": {
"id": "evt_1LcgJbIrzgNAlS3Thx0Y8mqE",
"created":12412512,
"approved": true,
"card": "cd_20230222023605609701",
"amount": "2100",
"currency": "USD",
"merchant_data": {
"category": "mens_womens_clothing_stores",
"category_code": "5691",
"city": "NEW YORK",
"country": "US",
"name": "GOOGLE",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "closed"
}
}
{
"event": "card_transaction",
"data": {
"id": "trn_0232452605609701",
"created": 12412512,
"card": "cd_20230222023605609701",
"amount": 2100,
"currency": "usd",
"merchant_data": {
"category": "computer_software_stores",
"category_code": "5734",
"city": "NEW YORK",
"country": "US",
"name": "GASGSAG",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "complete"
},
"sign": "123124124"
}
If the merchant reverse, or does not capture, until the authorization expired, we will refund the original deduct amount back to your account balance, you will receive a card_authorization event with true approved and reversed status, and will receive a card_transaction event with the reversed status that we want to tell you the merchant reverse the authorization or doesn't capture the authorization.
{
"event": "card_authorization",
"data": {
"id": "evt_1LcgJbIrzgNAlS3Thx0Y8mqE",
"created":12412512,
"approved": true,
"card": "cd_20230222023605609701",
"amount": "2100",
"currency": "USD",
"merchant_data": {
"category": "mens_womens_clothing_stores",
"category_code": "5691",
"city": "NEW YORK",
"country": "US",
"name": "GOOGLE",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "reversed"
}
}
{
"event": "card_transaction",
"data": {
"id": "trn_0232452605609701",
"created": 1670655510448,
"card": "cd_20230222023605609701",
"amount": 234,
"currency": "usd",
"merchant_data": {
"category": "computer_software_stores",
"category_code": "5734",
"city": "NEW YORK",
"country": "US",
"name": "GASGSAG",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "reversed"
},
"sign": "12521125215"
}
If the merchant issued a refund, Metaprise will send a card_transaction event with the refund status, the transaction number will not same as the original complete transaction number.
{
"event": "card_transaction",
"data": {
"id": "trn_0232452605609721",
"created": 1670655510441,
"card": "cd_20230222023605609701",
"amount": 234,
"currency": "usd",
"merchant_data": {
"category": "computer_software_stores",
"category_code": "5734",
"city": "NEW YORK",
"country": "US",
"name": "GASGSAG",
"network_id": "1234567890",
"postal_code": "11222",
"state": "NY"
},
"status": "refund"
},
"sign": "12521125215"
}