Refund an order

Smartpay will only process refunds following instructions made by you, our Merchant partner. You can issue a refund request via the Smartpay Dashboard or through a refund API call.

In the Smartpay dashboard

1. Find the order you wish to refund

After you login to your Smartpay dashboard you can see the list of your orders. You can search for a specific order by order id, reference, customer name and customer email.
Once you found the right order, click on it to open the order details page.

2. Refund the purchase

On the order details page click Refund.
Fill out the form with the amount you wish to refund and an optional description. Click Refund.

Using the Smartpay API

1. Get the order you wish to refund

Using the orderId for the order you wish to refund, retrieve the order object using the Smartpay API.

curl --request GET \
     --url '' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic {secretKey}'

The returned object will have a payments field with the payment id created for your order. You need to grab this paymentId to issue the refund.

  "id": "order_test_bA1znhGULw5lROfDTpHChv",
  "object": "order",
  "amount": 2100,
  "createdAt": 1644978270631,
  "currency": "JPY",
  "discounts": [],
  "expiresAt": 1645583167495,
  "lineItems": [
  "metadata": {},
  "payments": [
  "shippingInfo": {
  "status": "succeeded",
  "test": true,
  "updatedAt": 1644978437889

2. Issue the refund

Using the paymentId for your order, create a refund using the Smartpay API.

For full argument list please see the create a refund API endpoint. The following fields are mandatory:

  • amount: A positive amount representing how much of this payment to refund. You can refund only up to the remaining, unrefunded amount of the payment.
  • currency: Three-letter ISO currency code, in uppercase. Must be a supported currency.
  • payment: The unique identifier for the Payment object.
  • reason: The reason of the Refund, requested_by_customer or fraudulent
curl --request POST \
     --url \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic {secretKey}' \
     --header 'Content-Type: application/json' \
     --data '
     "amount": 1000,
     "currency": "JPY",
     "description": "Customer return",
     "lineItems": [],
     "payment": "payment_test_GDEATBKK8XAp9XGf6J4U4",
     "reason": "requested_by_customer",
     "reference": "my_merchant_refund_reference"
$api = new \Smartpay\Api(getenv('SECRET_KEY'), getenv('PUBLIC_KEY'));

$payment = $api->createRefund([
   'amount' => 1500,
   'currency' => 'JPY',
   'description' => 'Description for my Smartpay refund',
   'lineItems' => [],
   'payment' => 'payment_test_GDEATBKK8XAp9XGf6J4U4',
   'reason' => 'requested_by_customer',
   'reference' => 'my_merchant_refund_reference'
Smartpay.configure do |config|
  config.public_key = ENV['PUBLIC_KEY']
  config.secret_key = ENV['SECRET_KEY']

payment = Smartpay::Api.create_refund({
  amount: 1500,
  currency: 'JPY',
  description: 'Description for my Smartpay refund',
  lineItems: [],
  payment: 'payment_test_GDEATBKK8XAp9XGf6J4U4',
  reason: 'requested_by_customer',
  reference: 'my_merchant_refund_reference',
SECRET_KEY = os.environ.get('SECRET_KEY', '<YOUR_SECRET_KEY>')
PUBLIC_KEY = os.environ.get('PUBLIC_KEY', '<YOUR_PUBLIC_KEY>')

smartpay = Smartpay(SECRET_KEY, public_key=PUBLIC_KEY)

payment = smartpay.create_refund(
    description="Description for my Smartpay refund"