Partial Refunds

As you accept payments with the Rapyd API, you can offer top notch service to your customers by providing a way for full, or partial refunds. If you are an enterprise company, refunds could be a daily occurrence. As your business expands to new countries, you may have non-refundable fees you charge for cross-border and international orders.

You can make partial refunds multiple times for the same purchase until the refunds equal the full amount of the original transaction.

Refunds are made to the payment method used in the original payment transaction. For example if a customer pays by card, bank, or ewallet, the refund will return to the original payment method.

We created payments of different amounts of 400, 500, and 600, each with different payment methods. Let’s look at these partial refunds below:

Create Refund - Bank Transfer

The first refund is a $150 refund off of a $400 SGD purchase using FAST Bank Transfer.

Request

POST https://sandboxapi.rapyd.net/v1/refunds


{
   "payment": "payment_00cc3fd4e2bb7a411d555f0d07504253",
   "amount": "150"
 
}

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "c57d0fe3-a0f8-4465-b400-c7d0f5dcc62e"
   },
   "data": {
       "id": "refund_2e2666d8c85c98890d6ae57dea5ff753",
       "amount": 150,
       "payment": "payment_00cc3fd4e2bb7a411d555f0d07504253",
       "currency": "SGD",
       "failure_reason": "",
       "metadata": {},
       "reason": "",
       "status": "Pending",
       "receipt_number": 0,
       "created_at": 1683760296,
       "updated_at": 1683760296,
       "merchant_reference_id": "",
       "payment_created_at": 1683760252,
       "payment_method_type": "sg_fast_bank",
       "ewallets": [
           {
               "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 150
           }
       ],
       "proportional_refund": true,
       "merchant_debited_amount": null,
       "merchant_debited_currency": null,
       "fx_rate": null,
       "fixed_side": null
   }
}

Complete Refund

Request

POST https://sandboxapi.rapyd.net/v1/refunds/complete


{
 "token": "refund_2e2666d8c85c98890d6ae57dea5ff753"
}

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "ca8070ce-e506-466e-9363-d40f41b9ab71"
   },
   "data": {
       "id": "refund_2e2666d8c85c98890d6ae57dea5ff753",
       "amount": 150,
       "payment": "payment_00cc3fd4e2bb7a411d555f0d07504253",
       "currency": "SGD",
       "failure_reason": "",
       "metadata": {},
       "reason": "",
       "status": "Completed",
       "receipt_number": 0,
       "created_at": 1683760296,
       "updated_at": 1683760334,
       "merchant_reference_id": "",
       "payment_created_at": 1683760252,
       "payment_method_type": "sg_fast_bank",
       "ewallets": [
           {
               "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 150
           }
       ],
       "proportional_refund": true,
       "merchant_debited_amount": null,
       "merchant_debited_currency": null,
       "fx_rate": null,
       "fixed_side": null
   }
}

Retrieve Payment

Request

GET https://sandboxapi.rapyd.net/v1/payments/:payment

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "e2b416f8-9cac-4756-85a7-ca79114fd9e2"
   },
   "data": {
       "id": "payment_00cc3fd4e2bb7a411d555f0d07504253",
       "amount": 400,
       "original_amount": 400,
       "is_partial": false,
       "currency_code": "SGD",
       "country_code": "sg",
       "status": "CLO",
       "description": "Payment by bank transfer1",
       "merchant_reference_id": "",
       "customer_token": "cus_8b13394333ac71c75705797889b38927",
       "payment_method": "other_e8a9c26c02dfb022081484f1b0b62dcd",
       "payment_method_data": {
           "id": "other_e8a9c26c02dfb022081484f1b0b62dcd",
           "type": "sg_fast_bank",
           "category": "bank_transfer",
           "metadata": {},
           "image": "",
           "webhook_url": "",
           "supporting_documentation": "",
           "next_action": "not_applicable",
           "bic_swift": "",
           "account_last4": ""
       },
       "auth_code": null,
       "expiration": 1684969852,
       "captured": true,
       "refunded": true,
       "refunded_amount": 150,
       "receipt_email": "",
       "redirect_url": "",
       "complete_payment_url": "",
       "error_payment_url": "",
       "receipt_number": "",
       "flow_type": "",
       "address": null,
       "statement_descriptor": "********LLL",
       "transaction_id": "",
       "created_at": 1683760252,
       "metadata": {
           "merchant_defined": true
       },
       "failure_code": "",
       "failure_message": "",
       "paid": true,
       "paid_at": 1683760280,
       "dispute": null,
       "refunds": {
           "data": [
               {
                   "id": "refund_2e2666d8c85c98890d6ae57dea5ff753",
                   "amount": 150,
                   "currency": "SGD",
                   "failure_reason": "",
                   "metadata": {},
                   "reason": "",
                   "status": "Completed",
                   "receipt_number": 0,
                   "created_at": 1683760296,
                   "updated_at": 1683760334,
                   "merchant_reference_id": "",
                   "payment_created_at": 1683760252,
                   "payment_method_type": "",
                   "ewallets": [
                       {
                           "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
                           "amount": 150
                       }
                   ],
                   "proportional_refund": true,
                   "merchant_debited_amount": null,
                   "merchant_debited_currency": null,
                   "fx_rate": null,
                   "fixed_side": null
               }
           ],
           "has_more": false,
           "total_count": 1,
           "url": "/v1/refunds?payment=payment_00cc3fd4e2bb7a411d555f0d07504253"
       },
       "order": null,
       "outcome": null,
       "visual_codes": {},
       "textual_codes": {
           "DBS Account No": "6527273406013135"
       },
       "instructions": [
           {
               "name": "instructions",
               "steps": [
                   {
                       "step1": "Please Transfer funds to the provided DBS bank account using your Singapore based bank account via FAST (preferred), MEPS or GIRO."
                   }
               ]
           }
       ],
       "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
       "ewallets": [
           {
               "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 400,
               "percent": 100,
               "refunded_amount": 150
           }
       ],
       "payment_method_options": {},
       "payment_method_type": "sg_fast_bank",
       "payment_method_type_category": "bank_transfer",
       "fx_rate": 1,
       "merchant_requested_currency": null,
       "merchant_requested_amount": null,
       "fixed_side": "",
       "payment_fees": null,
       "invoice": "",
       "escrow": null,
       "group_payment": "",
       "cancel_reason": null,
       "initiation_type": "customer_present",
       "mid": "",
       "next_action": "not_applicable",
       "error_code": "",
       "remitter_information": {},
       "save_payment_method": true
   }
}

Create Refund - ewallet

The second refund is a $150 refund off of a $500 BRL (Brazilian real) purchase using PIX ewallet (br_pix_ewallet).

Request

POST https://sandboxapi.rapyd.net/v1/refunds


{
   "payment": "payment_5933d47b98d34631743eadcee7c2eb7c",
   "amount": "250"
 
}

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "f28ae0a2-be05-4520-acc7-52e9c91fa58d"
   },
   "data": {
       "id": "refund_bd04ebb61cff1e6c26e098b4182789e2",
       "amount": 250,
       "payment": "payment_5933d47b98d34631743eadcee7c2eb7c",
       "currency": "BRL",
       "failure_reason": "",
       "metadata": {},
       "reason": "",
       "status": "Pending",
       "receipt_number": 0,
       "created_at": 1683764508,
       "updated_at": 1683764508,
       "merchant_reference_id": "",
       "payment_created_at": 1683763681,
       "payment_method_type": "br_pix_ewallet",
       "ewallets": [
           {
               "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 250
           }
       ],
       "proportional_refund": true,
       "merchant_debited_amount": null,
       "merchant_debited_currency": null,
       "fx_rate": null,
       "fixed_side": null
   }
}


Complete Refund - ewallet

Request

POST https://sandboxapi.rapyd.net/v1/refunds/complete


{
 "token": "refund_bd04ebb61cff1e6c26e098b4182789e2"
}

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "dbdf411c-bbb2-42f9-98e4-3b8e0dc2fa68"
   },
   "data": {
       "id": "refund_bd04ebb61cff1e6c26e098b4182789e2",
       "amount": 250,
       "payment": "payment_5933d47b98d34631743eadcee7c2eb7c",
       "currency": "BRL",
       "failure_reason": "",
       "metadata": {},
       "reason": "",
       "status": "Completed",
       "receipt_number": 0,
       "created_at": 1683764508,
       "updated_at": 1683764562,
       "merchant_reference_id": "",
       "payment_created_at": 1683763681,
       "payment_method_type": "br_pix_ewallet",
       "ewallets": [
           {
               "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 250
           }
       ],
       "proportional_refund": true,
       "merchant_debited_amount": null,
       "merchant_debited_currency": null,
       "fx_rate": null,
       "fixed_side": null
   }
}

Retrieve Payment - ewallet

Request

GET https://sandboxapi.rapyd.net/v1/payments/:payment

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "9c193319-146c-41a2-a4e3-7a4bb7eac2f5"
   },
   "data": {
       "id": "payment_5933d47b98d34631743eadcee7c2eb7c",
       "amount": 500,
       "original_amount": 500,
       "is_partial": false,
       "currency_code": "BRL",
       "country_code": "br",
       "status": "CLO",
       "description": "Payment via Checkout",
       "merchant_reference_id": "950ae8c6-78",
       "customer_token": "cus_8c2074bbe3c978137e18f15a9d34ffeb",
       "payment_method": "other_c8e027e67a6068773ff2ea14216d4399",
       "payment_method_data": {
           "id": "other_c8e027e67a6068773ff2ea14216d4399",
           "type": "br_pix_ewallet",
           "category": "ewallet",
           "metadata": {},
           "image": "",
           "webhook_url": "",
           "supporting_documentation": "",
           "next_action": "not_applicable",
           "bic_swift": "",
           "account_last4": "",
           "email": "kylep+pix@rapyd.net",
           "cpf|cnpj": "11111111111",
           "last_name": "User",
           "first_name": "Test ",
           "address_zip": "1234",
           "address_city": "123 Test City",
           "address_name": "Test User",
           "phone_number": "5555555555",
           "address_state": "Santa Catarina",
           "address_line_1": "123 test Street"
       },
       "auth_code": null,
       "expiration": 1684368481,
       "captured": true,
       "refunded": true,
       "refunded_amount": 250,
       "receipt_email": "",
       "redirect_url": "",
       "complete_payment_url": "http://example.com/complete",
       "error_payment_url": "http://example.com/error",
       "receipt_number": "",
       "flow_type": "",
       "address": null,
       "statement_descriptor": "Test Business",
       "transaction_id": "",
       "created_at": 1683763681,
       "metadata": {
           "merchant_defined": true
       },
       "failure_code": "",
       "failure_message": "",
       "paid": true,
       "paid_at": 1683764495,
       "dispute": null,
       "refunds": {
           "data": [
               {
                   "id": "refund_bd04ebb61cff1e6c26e098b4182789e2",
                   "amount": 250,
                   "currency": "BRL",
                   "failure_reason": "",
                   "metadata": {},
                   "reason": "",
                   "status": "Completed",
                   "receipt_number": 0,
                   "created_at": 1683764508,
                   "updated_at": 1683764562,
                   "merchant_reference_id": "",
                   "payment_created_at": 1683763681,
                   "payment_method_type": "",
                   "ewallets": [
                       {
                           "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
                           "amount": 250
                       }
                   ],
                   "proportional_refund": true,
                   "merchant_debited_amount": null,
                   "merchant_debited_currency": null,
                   "fx_rate": null,
                   "fixed_side": null
               }
           ],
           "has_more": false,
           "total_count": 1,
           "url": "/v1/refunds?payment=payment_5933d47b98d34631743eadcee7c2eb7c"
       },
       "order": null,
       "outcome": null,
       "visual_codes": {},
       "textual_codes": {
           "code": "paygw_9d38e18711e25f60e5404e5b31110afe"
       },
       "instructions": [],
       "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
       "ewallets": [
           {
               "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 500,
               "percent": 100,
               "refunded_amount": 250
           }
       ],
       "payment_method_options": {},
       "payment_method_type": "br_pix_ewallet",
       "payment_method_type_category": "ewallet",
       "fx_rate": 1,
       "merchant_requested_currency": null,
       "merchant_requested_amount": null,
       "fixed_side": "",
       "payment_fees": null,
       "invoice": "",
       "escrow": null,
       "group_payment": "",
       "cancel_reason": null,
       "initiation_type": "customer_present",
       "mid": "",
       "next_action": "not_applicable",
       "error_code": "",
       "remitter_information": {},
       "save_payment_method": true
   }
}

Create Refund - Card

The third and last refund is a $600 GBP (British Pound) payment with a credit card.

Request

POST https://sandboxapi.rapyd.net/v1/refunds


 {
  "payment": "payment_c816af507dc625321c669baf61c08197",
   "amount": "300"
 
}

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "c685342c-c5c7-4007-9780-01e5dc10a1b3"
   },
   "data": {
       "id": "refund_2b62c205197fabed1020a0f9d2146aba",
       "amount": 300,
       "payment": "payment_c816af507dc625321c669baf61c08197",
       "currency": "GBP",
       "failure_reason": "",
       "metadata": {},
       "reason": "",
       "status": "Completed",
       "receipt_number": 0,
       "created_at": 1683922467,
       "updated_at": 1683922468,
       "merchant_reference_id": "",
       "payment_created_at": 1683922446,
       "payment_method_type": "gb_visa_card",
       "ewallets": [
           {
               "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 300
           }
       ],
       "proportional_refund": true,
       "merchant_debited_amount": null,
       "merchant_debited_currency": null,
       "fx_rate": null,
       "fixed_side": null
   }
}

Retrieve Payment

Request

GET https://sandboxapi.rapyd.net/v1/payments/:payment

Response

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "aecac1aa-6235-4a63-b63e-0deb558377dd"
   },
   "data": {
       "id": "payment_c816af507dc625321c669baf61c08197",
       "amount": 600,
       "original_amount": 600,
       "is_partial": false,
       "currency_code": "GBP",
       "country_code": "GB",
       "status": "CLO",
       "description": "",
       "merchant_reference_id": "",
       "customer_token": "cus_183225bd57e4bc4967bf8b4ddc9c6144",
       "payment_method": "card_dda862f5041eddf8c3b6fa8dbcbf8ab5",
       "payment_method_data": {
           "id": "card_dda862f5041eddf8c3b6fa8dbcbf8ab5",
           "type": "gb_visa_card",
           "category": "card",
           "metadata": {
               "merchant_defined": true
           },
           "image": "",
           "webhook_url": "",
           "supporting_documentation": "",
           "next_action": "not_applicable",
           "name": "John Doe",
           "last4": "1111",
           "acs_check": "unchecked",
           "cvv_check": "unchecked",
           "bin_details": {
               "type": null,
               "brand": null,
               "level": null,
               "issuer": null,
               "country": null,
               "bin_number": "411111"
           },
           "expiration_year": "23",
           "expiration_month": "12",
           "fingerprint_token": "ocfp_2a694038316f52122bbbb3ae926cfda9"
       },
       "auth_code": null,
       "expiration": 1684527246,
       "captured": true,
       "refunded": true,
       "refunded_amount": 300,
       "receipt_email": "",
       "redirect_url": "",
       "complete_payment_url": "",
       "error_payment_url": "",
       "receipt_number": "",
       "flow_type": "",
       "address": null,
       "statement_descriptor": "Test Business",
       "transaction_id": "",
       "created_at": 1683922446,
       "metadata": {},
       "failure_code": "",
       "failure_message": "",
       "paid": true,
       "paid_at": 1683922446,
       "dispute": null,
       "refunds": {
           "data": [
               {
                   "id": "refund_2b62c205197fabed1020a0f9d2146aba",
                   "amount": 300,
                   "currency": "GBP",
                   "failure_reason": "",
                   "metadata": {},
                   "reason": "",
                   "status": "Completed",
                   "receipt_number": 0,
                   "created_at": 1683922467,
                   "updated_at": 1683922468,
                   "merchant_reference_id": "",
                   "payment_created_at": 1683922446,
                   "payment_method_type": "",
                   "ewallets": [
                       {
                           "ewallet": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
                           "amount": 300
                       }
                   ],
                   "proportional_refund": true,
                   "merchant_debited_amount": null,
                   "merchant_debited_currency": null,
                   "fx_rate": null,
                   "fixed_side": null
               }
           ],
           "has_more": false,
           "total_count": 1,
           "url": "/v1/refunds?payment=payment_c816af507dc625321c669baf61c08197"
       },
       "order": null,
       "outcome": null,
       "visual_codes": {},
       "textual_codes": {},
       "instructions": [],
       "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
       "ewallets": [
           {
               "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
               "amount": 600,
               "percent": 100,
               "refunded_amount": 300
           }
       ],
       "payment_method_options": {},
       "payment_method_type": "gb_visa_card",
       "payment_method_type_category": "card",
       "fx_rate": 1,
       "merchant_requested_currency": null,
       "merchant_requested_amount": null,
       "fixed_side": "",
       "payment_fees": null,
       "invoice": "",
       "escrow": null,
       "group_payment": "",
       "cancel_reason": null,
       "initiation_type": "customer_present",
       "mid": "",
       "next_action": "not_applicable",
       "error_code": "",
       "remitter_information": {},
       "save_payment_method": true
   }
}
2 Likes