How do I implement refunds via API for Maya Vault payments?

General
1

How do I refund a payment that was made with a vaulted card in Maya Vault (Create Customer Payment) and captured with Capture Payment via API?

2

To refund a payment made with a vaulted card via Maya Vault, use the /p3/refund endpoint. Ensure the following:

  • The payment has been successfully captured and is in the PAYMENT_SUCCESS state.
  • The refund request is made after 12:00 AM GMT+8 of the transaction date.
  • The total refund amount does not exceed the original captured amount.

Use the captureTransactionReferenceNo (from the capture response) as the transactionReferenceNo in the refund request body. You may perform full or partial refunds.

Sample Request:

POST /p3/refund
Authorization: Basic <base64-encoded-secret-key>
Content-Type: application/json

{
  "transactionReferenceNo": "<captureTransactionReferenceNo>",
  "amount": 100,
  "currency": "PHP"
}

Refunds are processed synchronously. The refunded amount will be credited to the customer’s card according to their issuing bank’s timeline (typically 7–14 days for credit cards). For reconciliation, use the Retrieve Payment via ID endpoint.

Note: The /capturev1payment endpoint is part of the Auth and Capture flow, but refunds are handled via the Payments Processing Platform’s /p3/refund endpoint, not the Vault-specific endpoints.

For Sandbox concerns and other technical implementation inquiries, please get in touch with us via:

  • Sandbox Health Page: Check real-time service status updates.
  • Maya Developer Hub Service Desk: File
    a ticket in Sandbox.

To Know More:

We value your input and would love to hear your insights. Please submit you feedback here.

3

Hi @squishyonigiri, Just to correct the AI’s previous response, a captured payment with a status of PAYMENT_SUCCESS can be refunded after the 12 am cutoff time. Here you can use the Maya Manager or the refund API.

Reference: Authorize (Hold) and Capture