Premium Refund

(TODO: Improve the texts. That was migrate as it is from confluence)

This document aims to aid the payment gateway users on how to request a premium refund (refunding a bunch of payments or all recurring payments related).

Request

Information	Description
Host	Provided by boltPay
Method	PUT
Endpoint	/v1/premium/refund
Body	raw
Content-Type	application/json

Request Body

Rules:

The recurring ID will be used to refund all payments related to it.

If no payment was sent in the payments the API will refund all payments. If some payment was sent in the payments the API will check all the payments and refund only the payments related to the recurring ID.

If no recurring ID was sent, the API will get the first payment and check if there is a recurring ID related to it on the database. If it’s found will use the found recurring ID to do the process above.

Attribute	Required	Default	Description
recurringId	Only if no payments were sent	Empty String	Recurring ID to refund all related payments, or to check the sent payment list and refund the payments from the the related payments list.
disableRecurring	No	true	Disables the recurring to no more able to be used to create payments
payments	Only if no recurringId was sent	Empty String	List of payment IDs to be refund ex: [ "6553bc171e680820f2ff45f2", "6553bc1f1e680820f2ff461a", "6553bdb9538cddf93bd9d4e1"]

Example with all possible attributes:

{
  "recurringId": "6553bdd2538cddf93bd9d520",
  "disableRecurring": false,
  "payments": [
    "6553bc171e680820f2ff45f2",
    "6553bc1f1e680820f2ff461a",
    "6553bdb9538cddf93bd9d4e1",
    "6553bc271e680820f2ff4642",
    "6553bc301e680820f2ff466a"
  ]
}

Response

The API will save the status of each payment refund request and respond with each payment refund status (success or error).

Possible Scenarios

Case 1: Request to refund using the recurring ID and disable the recurring.

Request:

{
  "recurringId": "6553b5da538cddf93bd9d468"
}

Response:

{
  "paymentStatus": [
    {
      "paymentId": "6553b5bd538cddf93bd9d429",
      "refundStatus": "SENT_FOR_REFUND"
    },
    {
      "paymentId": "6553b67a0c52e66db05ee751",
      "refundStatus": "SENT_FOR_REFUND"
    },
    {
      "paymentId": "6553b6590c52e66db05ee729",
      "refundStatus": "SENT_FOR_REFUND"
    }
  ],
  "recurringStatus": "INACTIVE"
}

---

Case 2: Request a bunch of payments and recurring continue active.

Request:

{
  "disableRecurring": false,
  "payments": [
    "6553bc271e680820f2ff4642",
    "6553bc301e680820f2ff466a",
    "6553bc671e680820f2ff4692",
    "6553bc6f1e680820f2ff46ba"
  ]
}

Response:

{
  "paymentStatus": [
    {
      "paymentId": "6553bc6f1e680820f2ff46ba",
      "refundStatus": "SENT_FOR_REFUND"
    },
    {
      "paymentId": "6553bc301e680820f2ff466a",
      "refundStatus": "SENT_FOR_REFUND"
    },
    {
      "paymentId": "6553bc271e680820f2ff4642",
      "refundStatus": "SENT_FOR_REFUND"
    },
    {
      "paymentId": "6553bc671e680820f2ff4692",
      "refundStatus": "SENT_FOR_REFUND"
    }
  ],
  "recurringStatus": "ACTIVE"
}

---

Case 3: Send a bunch of payments and the recurring ID and refund only the related payments.

Request:

{
  "recurringId": "6553bdd2538cddf93bd9d520",
  "disableRecurring": false,
  "payments": [
    "6553bc171e680820f2ff45f2",
    "6553bc1f1e680820f2ff461a",
    "6553bdb9538cddf93bd9d4e1",
    "6553bc271e680820f2ff4642",
    "6553bc301e680820f2ff466a"
  ]
}

Response:

{
  "paymentStatus": [
    {
      "paymentId": "6553bc171e680820f2ff45f2",
      "refundStatus": "FAILED",
      "error": "Payment does not belong to recurring: 6553bdd2538cddf93bd9d520"
    },
    {
      "paymentId": "6553bc1f1e680820f2ff461a",
      "refundStatus": "FAILED",
      "error": "Payment does not belong to recurring: 6553bdd2538cddf93bd9d520"
    },
    {
      "paymentId": "6553bc271e680820f2ff4642",
      "refundStatus": "FAILED",
      "error": "Payment does not belong to recurring: 6553bdd2538cddf93bd9d520"
    },
    {
      "paymentId": "6553bc301e680820f2ff466a",
      "refundStatus": "FAILED",
      "error": "Payment does not belong to recurring: 6553bdd2538cddf93bd9d520"
    },
    {
      "paymentId": "6553bdb9538cddf93bd9d4e1",
      "refundStatus": "SENT_FOR_REFUND"
    }
  ],
  "recurringStatus": "ACTIVE"
}

Possible Problems

1. If the payment list is too big, the response may take a little bit or could cause a request rejection from the PSP (Payment Service Provider) side thinking it is a DDoS attack.
   • Solution: Move this refund to a scheduler that will delay the requests between its self
2. Payment Gateway could become slow during the bunch of payment requests.
   • Solution: Remove this process from the payment gateway to a micro-service that will call each refund using the payment gateway but with a delay.