Guides
Start typing to search…

Transaction lifecycle

Auth Request

sequenceDiagram
    participant Merchant
    participant DogPay
    participant Partner

    Merchant ->> DogPay: Auth Request
    DogPay -->> Partner: Webhook (card.transaction) 
{
    "id": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505171223219717623",
    "transactionId": null,
    "currency": "USD",
    "fee": "1.02000000",
    "amount": "1.30000000",
    "type": "consumption",
    "status": "pending",
    "createAt": "2025-05-17T04:23:21.973Z",
    "completeAt": "2025-05-17T04:23:21.971Z",
    "detail": "Generic Rubber Chips Laylaberg CN",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": "USD",
    "localAmount": "1.30000000",
    "merchantInfo": {
        "name": "Generic Rubber Chips",
        "city": "Laylaberg",
        "country": "CN",
        "mcc": "2686"
    }
}

Cumulative debit amount = amount + fee

Auth Request -> Settlement

sequenceDiagram
    participant Merchant
    participant DogPay
    participant Partner

    Merchant ->> DogPay: Auth Request
    DogPay -->> Partner: Webhook (card.transaction)   
    DogPay ->> Partner: Settlement
    DogPay -->> Partner: Webhook (card.transaction.update)   

{
    "id": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cursorId": "1923595170488516609",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505171223219717623",
    "currency": "USD",
    "fee": "1.02000000",
    "amount": "1.30000000",
    "type": "consumption",
    "status": "completed",
    "createAt": "2025-05-17T04:23:21.973Z",
    "completeAt": "2025-05-18T02:08:00.130Z",
    "detail": "Generic Rubber Chips Laylaberg CN",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": "USD",
    "localAmount": "1.30000000",
    "merchantInfo": {
        "name": "Generic Rubber Chips",
        "city": "Laylaberg",
        "country": "CN",
        "mcc": "2686"
    }
}

Auth Request -> Settlement (amount changed)

**When the order amount changes, a new transaction order will be generated. This new order will have a field called <preTransactionId> to associate it with the original order. **

sequenceDiagram
    participant Merchant
    participant DogPay
    participant Partner

    Merchant ->> DogPay: Auth Request
    DogPay -->> Partner: Webhook (card.transaction)
    DogPay ->> Partner: Settlement
    DogPay -->> Partner: Webhook(card.transaction.update) [Pre transaction]
    rect rgb(191, 223, 255)
    DogPay ->> Partner: Settlement amount exceeds authorized amount.
    DogPay -->> Partner: Webhook(card.transaction) [New transaction]
    end

Auth Request

{
    "id": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505171223219717623",
    "transactionId": null,
    "currency": "USD",
    "fee": "1.02000000",
    "amount": "1.30000000",
    "type": "consumption",
    "status": "pending",
    "createAt": "2025-05-17T04:23:21.973Z",
    "completeAt": "2025-05-17T04:23:21.971Z",
    "detail": "Generic Rubber Chips Laylaberg CN",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": "USD",
    "localAmount": "1.30000000",
    "merchantInfo": {
        "name": "Generic Rubber Chips",
        "city": "Laylaberg",
        "country": "CN",
        "mcc": "2686"
    }
}

amount increased

{
    "id": "d4842fbd-d2d3-4f0a-97f1-467473a79b6b",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cursorId": "1923923494137237506",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505181008004296568",
    "currency": "USD",
    "fee": "0.00000000",
    "amount": "0.31000000",
    "type": "settlement_debit",
    "status": "completed",
    "createAt": "2025-05-18T02:08:00.072Z",
    "completeAt": "2025-05-18T02:08:00.429Z",
    "detail": "",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": null,
    "localAmount": "0.00000000",
    "preTransactionId": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "merchantInfo": null
}

Cumulative debit amount = amount + fee

amount decreased

{
    "id": "d4842fbd-d2d3-4f0a-97f1-467473a79b6b",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cursorId": "1923923494137237506",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505181008004296568",
    "currency": "USD",
    "fee": "0.00000000",
    "amount": "0.31000000",
    "type": "settlement_refund",
    "status": "completed",
    "createAt": "2025-05-18T02:08:00.072Z",
    "completeAt": "2025-05-18T02:08:00.429Z",
    "detail": "",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": null,
    "localAmount": "0.00000000",
    "preTransactionId": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "merchantInfo": null
}

Auth Request -> Reversal

If a transaction order is reversed, a new transaction order will be generated. The new order contains the field <preTransactionId>, which is used to link to the original order.

sequenceDiagram
    participant Merchant
    participant DogPay
    participant Partner

    Merchant ->> DogPay: Auth Request
    DogPay -->> Partner: Webhook (card.transaction)
    Merchant ->> DogPay: Reversal(Transaction not settle)
    DogPay ->> Partner:  Settlement
    DogPay -->> Partner: Webhook(card.transaction.update) [Pre transaction]
    rect rgb(191, 223, 255)
    DogPay -->> Partner: Webhook(card.transaction) [New transaction]
    end

{
    "id": "d4842fbd-d2d3-4f0a-97f1-467473a79b6b",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cursorId": "1923923494137237506",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505181008004296568",
    "currency": "USD",
    "fee": "0.01000000",
    "amount": "0.31000000",
    "type": "reversal",
    "status": "completed",
    "createAt": "2025-05-18T02:08:00.072Z",
    "completeAt": "2025-05-18T02:08:00.429Z",
    "detail": "",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": null,
    "localAmount": "0.00000000",
    "preTransactionId": "f16e76f7-f71f-42ec-9df7-d9bcab9212f7",
    "merchantInfo": null
}

Cumulative Refund Amount = amount - fee

Refund

New transaction and not associated with the previous one.

sequenceDiagram
    participant Merchant
    participant DogPay
    participant Partner

    Merchant ->> DogPay: Auth Request
    DogPay -->> Partner: Webhook (card.transaction)
    DogPay ->> Partner: All Settlement
    DogPay -->> Partner: Webhook(card.transaction.update)
    Merchant ->> DogPay: Refund
    rect rgb(191, 223, 255)
    DogPay -->> Partner: Webhook(card.transaction)
    end

{
    "id": "d4842fbd-d2d3-4f0a-97f1-467473a79b6b",
    "cardId": "12327a6b-2230-4213-8b1a-bae56aeb8456",
    "cursorId": "1923923494137237506",
    "cardChannel": "c_002_budget",
    "entityId": "a1a8a554-40dd-41a5-8698-461a9dee6349",
    "orderNum": "202505181008004296568",
    "currency": "USD",
    "fee": "0.01000000",
    "amount": "0.31000000",
    "type": "refund",
    "status": "completed",
    "createAt": "2025-05-18T02:08:00.072Z",
    "completeAt": "2025-05-18T02:08:00.429Z",
    "detail": "",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": null,
    "localAmount": "0.00000000",
    "preTransactionId": null,
    "merchantInfo": null
}

Cumulative Refund Amount = amount - fee

Auth Request -> Declined Refund

Sometimes, the authorization transaction has been completed at dogpay, but due to some network fluctuations or other reasons, the authorization has not been completed on the bank's side, resulting in a failure of this transaction. In this case, a refusal to refund will be generated to return the customer's funds.

Auth transaction

{
    "id": "b98936be-3f56-4bf2-af32-e75eddba5833",
    "cardId": "fc05e981-426e-4364-ae1b-9e708ffdda3e",
    "cardChannel": "c_002_budget",
    "entityId": "f42a2777-1cbc-428c-a271-aebbbdc658df",
    "orderNum": "202505201838063203902",
    "currency": "USD",
    "fee": "0.53000000",
    "amount": "2.00000000",
    "type": "consumption",
    "status": "pending",
    "createAt": "2025-05-20T10:38:06.317Z",
    "completeAt": "2025-05-20T10:38:06.326Z",
    "detail": "FACEBK *ZVF8KRQXN2 fb.me/ads IE",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": "USD",
    "localAmount": "2.00000000",
    "merchantInfo": {
        "name": "FACEBK *ZVF8KRQXN2",
        "city": "fb.me/ads",
        "country": "IE",
        "mcc": "7311"
    }
}

Declined refund transaction

{
    "id": "9cd70700-4a7d-4eed-8e77-dfb2a1b9966c",
    "cardId": "fc05e981-426e-4364-ae1b-9e708ffdda3e",
    "cardChannel": "c_002_budget",
    "entityId": "f42a2777-1cbc-428c-a271-aebbbdc658df",
    "orderNum": "202505201838100487130",
    "currency": "USD",
    "fee": "0.00000000",
    "amount": "2.53000000",
    "type": "declined_refund",
    "status": "completed",
    "createAt": "2025-05-20T10:38:10.031Z",
    "completeAt": "2025-05-20T10:38:10.048Z",
    "detail": "",
    "tradeTag": null,
    "reasonCode": 0,
    "localCurrency": null,
    "localAmount": "0.00000000",
    "preTransactionId": "b98936be-3f56-4bf2-af32-e75eddba5833",
    "merchantInfo": null
}

Total amount = amount

Updated 3 months ago