Void API usage as reversal

General
1

This is regarding ongoing discussion for using void API as Reversal API for Stripe

Could you please advise on below queries?

  1. Whether transactions processed through this reversal API would be excluded from settlement files
  2. In the current integration, if Boku processes a refund within 24 hours (using void API) , is the transaction included in the daily settlement file or excluded?

Additionally, Regarding your response over email..
You can only trigger the reversal if the charge is a success, otherwise there is no transaction to reverse in the first place if charge did not succeed.

Could you please advise on below queries as well?

  1. the merchant has an SLA of say 5 secs and for some reason the transaction got timed out due to network delay but the transaction was success at Maya’s case. Now merchant triggers the void API to reverse the amount to user’s account since they do not know the status, what would be the response from Maya in this case?
  2. Likewise, if a transaction fails at Maya’s end as the transaction got timed out and the merchant triggers the void API, what will be the response from Maya in this case?
2

Hi @jwadkar, I’d like to understand what solution you’re trying to integrate with Maya? Is it Maya Checkout?

For Checkout or online payments, there is no reversal API; you can only perform a void (same day) or a refund (the day after the transaction) to a successful payment transaction.

  1. Voided transactions will not be reflected on the settlement since the transaction has not been cleared.
  2. Refund transactions will be reflected as a separate line item on the settlement file

References:

For handling network delays, one of the best practices is to implement Webhooks. This will notify your server in real-time on the payment event, whether the transaction is a success or a failure. If, for whatever reason, you’re unable to receive the Webhooks, you can check the transaction status first by using the Retrieve Payment endpoints: Retrieve Payment via ID

If your platform decides to void the transaction, Maya will void it if the transaction has a PAYMENT_SUCCESS status.

References:

3

Hi @frances.kagahastian,

Renzo here RM of Boku. Integration is with PWM as a Payment Facilitator :slight_smile:

4

Hi @jwadkar,

Confirming that transactions that have been VOIDED using VOID API, will not be part of settlement report files. Refunds (not same day, using Refund API) however are part of the reports.

5

Hi @renzoatos @frances.kagahastian

Thank you for your response.

We are currently using below API for voiding the transaction if it arrives before 24 hrs.

2026-02-02 10:58:55,455 (mtQueueDefaultMessageListenerContainer-2) DEBUG [org.apache.http.wire] [trkId=ABF-3dbmnz3l] [trxId=1773956935088014398][msisdn=A_184ded850583045d] http-outgoing-42818 >> “POST /payments/v1/payment-rrns/b6yp1g3qtidlqzhceiq6w9th/voids HTTP/1.1[\r][\n]”

We are mainly looking for the reversal API for the tokenised/subscription based charge post wallet linking, where there is no user intervention and merchants would generally prefer to reverse the transaction rather than calling a status check API.

@frances.kagahastian Could you please confirm if your above response is applicable for tokenised charge as well?

  1. There is no reversal API; you can only perform a void (same day) or a refund (the day after the transaction) to a successful payment transaction.”
  2. For handling network delays, one of the best practices is to implement Webhooks. This will notify your server in real-time on the payment event, whether the transaction is a success or a failure. If, for whatever reason, you’re unable to receive the Webhooks, you can check the transaction status first by using the Retrieve Payment endpoints: Retrieve Payment via ID - We believe webhooks are not applicable for tokenised charge right?
6

What do you mean by tokenized charge? What Maya endpoint are you calling?

Just to clarify, after the Wallet Link creation, you’re using the Execute Wallet Link Payment endpoint? If yes, webhooks are still applicable, because this is the payment leg of the API.

https://pg-sandbox.paymaya.com/payby/v2/paymaya/link/{linkId}/execute

7

Yes, that’s correct we are using execute wallet link API for recurring payments. Hence could you please whether true reversals are applicable in this case based on the scenario I shared above?

8

Sharing for reference:

2026-01-07 07:45:36,168 (mtQueueDefaultMessageListenerContainer-15) DEBUG [c.b.c.lib.springweb.SLAReadyRestTemplate] [trkId=ABF-3DHEHDFr] [trxId=b4re90zaha2iyplx41lg1jft][api=CHARGE_WITH_TOKEN][msisdn=A_187be4ff0a43004f] HTTP POST https://pg.paymaya.com/payby/v2/paymaya/link/de9b8cf7-7cb6-4e62-85bf-f01a87836984/execute

2026-01-07 07:45:36,169 (mtQueueDefaultMessageListenerContainer-15) DEBUG [org.apache.http.wire] [trkId=ABF-3DHEHDFr] [trxId=b4re90zaha2iyplx41lg1jft][api=CHARGE_WITH_TOKEN][msisdn=A_187be4ff0a43004f] http-outgoing-27659 >> “POST /payby/v2/paymaya/link/de9b8cf7-7cb6-4e62-85bf-f01a87836984/execute HTTP/1.1[\r][\n]”

2026-01-07 07:45:36,172 (mtQueueDefaultMessageListenerContainer-15) DEBUG [org.apache.http.wire] [trkId=ABF-3DHEHDFr] [trxId=b4re90zaha2iyplx41lg1jft][api=CHARGE_WITH_TOKEN][msisdn=A_187be4ff0a43004f] http-outgoing-27659 >> “{“totalAmount”:{“currency”:“PHP”,“value”:“1.00”},“requestReferenceNumber”:“b4re90zaha2iyplx41lg1jft”,“metadata”:{“pf”:{“smi”:“Boku2”,“smn”:“Boku2 PayMaya Test”,“mci”:“Seattle”,“mpc”:“608”,“mco”:“USA”,“mst”:“WA”}}}”

9

Hi @jwadkar I think the forums are public, not sure if people here can check your specific transaction. Maybe you need to contact Maya’s call center, if you want this to be checked?

1 Like
10

Yes, a transaction can be voided/refunded after a successful Execute Wallet Link Payment transaction. Just ensure to use the correct endpoints Void (for same day transactions), and Refund (for previous days transactions).

11

@frances.kagahastian Thanks for your response. I understand that void transaction can only be used if the charge was success. Can you please confirm if it can be used in the above scenarios as well? If yes, what will be Maya’s response?

12

@jwadkar, Void and refund requests are validated against the actual transaction state in Maya. Below is how Maya behaves in each use case:

1. Transaction times out on the merchant side, but is successful on Maya’s end

  • What happens: The payment may still be completed at Maya, even if your system did not receive the final response or webhook notification within your SLA (e.g., 5 seconds).
  • When the merchant subsequently triggers the Void API:
    • If the transaction is still eligible for void (within the same day before 11:59 PM (GMT+8)), Maya will process the void accordingly.
    • If the transaction is no longer eligible for void (the day after the transaction, starting 12:00 AM (GMT+8)), the void request will fail.

2. Transaction times out and fails on Maya’s end

  • No successful charge exists on Maya’s side.
  • When the merchant triggers the Void API:
    • Maya will return an error indicating that the payment does not exist or is not voidable, since there is no successful transaction to void.

Recommended best practice:

  • Do not rely solely on timeout responses.
  • Always reconcile the transaction status using:
    • Webhook events (when enabled), and/or
    • Transaction inquiry
  • Trigger void or refund only after confirming the actual transaction status.
1 Like
13

thanks @genson.cerezo !