Skip to main content

Refunds

This flow is followed by a merchant who wants to refund a payment. Using the provided APIs, third-party software can request a refund for a specific payment and amount and check for the refund state

danger

In a winning transaction the buyer does not pay out any money to the merchant, consequently, no refund is possible. So, ONLY payed transactions are refundable. In case of failure during refund, it is possible to retry the operation.

APIs required​

info

Any change in the state of the transaction is notified via the WebHook reachable from the callbackUrl. In any case, it is possible to obtain the current status of the refund request by calling the api getRefundPaymentRequest.

Sequence Diagram​

sequenceDiagram participant MS as Maypay Server participant ES as eCommerce Server participant EC as eCommerce Client rect rgb(255, 255, 255) EC->>ES: Order Refund activate ES ES->>MS: POST refundPaymentRequest(paymentRequestId, transactionId, amount) activate MS MS-->>ES: payment request update via callback url - WAITING_REFUND MS->>ES: 200 OK - refund request deactivate MS ES->>EC: refund request created deactivate ES MS->>MS: Process Refund MS-->>ES: payment request update via callback url - REFUNDED end

How to test​

API integration and testing is made easier by a Sandbox Test Environment provided by Maypay. This environment simulates the creation of transactions and interaction with the buyer, giving the possibility to decide what the payment outcome will be.

Prerequisites​

There is no difference between production and sandbox API endpoints. The distinction between production and sandbox API calls is made by the type of API Key. API Keys can be created via the merchant portal Maypay Business and can be of 2 types:

  • Production: API Keys to be used for the production environment
  • Sandbox: API Keys to be used for the sandbox environment

Test Refunds​

In order to test the refundPaymentRequest it is first necessary to complete a payment, however, it can only be refunded if the transaction is not a winning one. In the latter case, the buyer does not pay out any money to the merchant, consequently, no refund is possible.

caution

It is possible to refund only payment with isWinningTransaction=false and with one of the following states values:

  • PAYED
  • REFUND_FAILED

All the other attempts to refund a payment that does not meet the above requirements will lead to the error Transaction is not refundable.

In the test environment, no real payment will be created, therefore the transactionId is not available and the parameter paymentRequestId becomes mandatory. However, it is possible to make use of the transactionId parameter to instruct the test environment what outcome of the refund should be. This can be done by using one of the following transaction IDs:

  • sandbox_successful_refund_transaction: The transaction will be moved into the WAITING_REFUND state and eventually into the REFUNDED state.
  • sandbox_failed_refund_transaction: The transaction will be moved into the REFUNDED state and eventually into the REFUND_FAILED state.

The first payment status change is immediate, while the second one will occur within 5 minutes. This awaiting time is meant to simulate the delay that exists in the real environment between the time of the request and the time when the outcome of the refund is notified, which can be hours or days long, depending on the buyer's bank.

If no transactionId is provided to the API, then the transaction will be moved into the WAITING_REFUND state and eventually into the REFUNDED state.

Also in this environment, the result will be sent to the eCommerce server via the endpoint indicated by the callbackUrl.