Skip to main content
In this guide, you will find instructions on refunding a previously created payment on Yuno.

​
Requirements

To refund a payment, you need to:
  • Access your API credentials on the Yuno Dashboard, which consist of:
    • public-api-key
    • private-secret-key
  • Have the payment identification data received after creating the payment using the Create Payment endpoint and the capture data from the capture operation executed using the Capture Payment:
    • id: The unique identifier of the payment, obtained from the parameter id after creating the payment.
    • transaction_id: The unique identifier of the transaction. You will use a different source for this information, depending on how you captured the payment.
      • If you created and captured the payment using only one operation, you obtain the transaction_id from the parameter transaction.id after creating the payment with the Create Payment endpoint.
      • If you performed the authorization and then the payment capture, you will use the transaction_id from the parameter id received after capturing the payment using the Capture Payment endpoint.
      • If you retrieve the payment later with the Retrieve Payment by ID endpoint, take the id of the transaction whose type is PURCHASE or CAPTURE from the transactions array. The id of a REFUND transaction cannot be used to refund.
Explore Yuno Postman CollectionsYuno provides Postman Collections that you can use to replicate the use cases locally.

​
Refund a payment

If you initiate a refund, it will reimburse a charge created earlier but not yet refunded. The amount will be credited back to the original payment method that was charged. Yuno offers three endpoints to refund a payment. They share the same request body, and every call requires an X-Idempotency-Key header with a new value for each attempt:
  • Refund Payment: Refunds a specific transaction. Provide the payment id and the transaction_id. Use it when you want to control exactly which transaction is refunded.
  • Cancel or Refund a Payment: Works at the payment level, so no transaction_id is needed. Yuno cancels the payment if it has not been captured and refunds it if it has. The reason field is required.
  • Cancel or Refund a Payment with Transaction: Applies the same automatic decision to a specific transaction_id.
In addition, you need to inform the amount to be refunded using the object amount in the request body:
  • Complete refund: Leave the amount empty.
  • Partial refund: Provide the refund value using the parameter amount.
One refund at a timeDo not start a new refund on the same transaction while a previous one is still in progress. Wait until the previous refund reaches a final status (SUCCEEDED, DECLINED, or ERROR) before sending the next one.

​
Refund results

The response contains a new transaction with transaction.type = REFUND. Use its status to interpret the result of the refund:
  • SUCCEEDED: The provider accepted the refund. For a complete refund, the payment moves to status = REFUNDED and sub_status = REFUNDED. For a partial refund, the payment keeps status = SUCCEEDED and its sub_status changes to PARTIALLY_REFUNDED.
  • PENDING: The provider confirms the refund asynchronously. The payment shows status = REFUNDED and sub_status = PENDING_PROVIDER_CONFIRMATION until the confirmation arrives. Use webhooks or the retrieve endpoints to get the final status, as described in Check the payment status.
  • DECLINED or ERROR: The provider, or the cardholder’s issuer, rejected the refund. No funds move and the payment keeps its previous status and sub_status. Check the transaction’s response_code and response_message for the reason. Once the cause is solved, send the refund again with a new X-Idempotency-Key, or set simplified_mode to true in the request so Yuno retries the refund automatically, as described in Transaction Retries.
Provider-dependent behaviorWhether a refund is confirmed synchronously or stays PENDING, whether partial refunds and several refunds on the same transaction are allowed, and for how long after the purchase a refund is accepted all depend on the provider that processed the payment. Many card acquirers process a refund as an online transaction against the cardholder’s account and answer with a final status right away, which also means the issuer can decline it. If your integration relies on any of these behaviors, confirm them with Yuno for the providers in your routing.
Refund Processing TimeRefunds processing time varies depending on the payment type. While in test mode, refunds are processed instantly in the Sandbox environment. If your sandbox connection points to the provider’s own test environment, the refund is sent to that environment and requires a successful test purchase first.

​
Check the payment status

If, for some reason, you need to confirm the payment refund: