Initiate Refund | Refunds API

curl --request POST \
  --url https://api.atoa.me/api/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentRequestId": "<string>",
  "amount": 123,
  "currency": "<string>",
  "refundNotes": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.atoa.me/api/refund"

payload = {
    "paymentRequestId": "<string>",
    "amount": 123,
    "currency": "<string>",
    "refundNotes": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    paymentRequestId: '<string>',
    amount: 123,
    currency: '<string>',
    refundNotes: '<string>',
    metadata: {}
  })
};

fetch('https://api.atoa.me/api/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.atoa.me/api/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'paymentRequestId' => '<string>',
    'amount' => 123,
    'currency' => '<string>',
    'refundNotes' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.atoa.me/api/refund"

	payload := strings.NewReader("{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.atoa.me/api/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
    "refundId": "a7c82e45-9f31-42b6-8d15-7e63f1b92c4d",
    "paymentRequestId": "5e8b2c73-1f64-4a97-9c38-d2f6ae15b8c2",
    "paymentIdempotencyId": "ATOA1234567890123",
    "status": "INITIATED",
    "paidAmount": "250.75",
    "refundAmount": "25.50",
    "currency": "GBP",
    "refundNotes": "Customer requested refund",
    "orderId": "987654321",
    "createdAt": "2023-11-15T14:32:45.789Z",
    "updatedAt": "2023-11-15T14:32:45.789Z"
}

{
  "name": "BadRequestException",
  "message": "Refund amount exceeded"
}

{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": []
}

{
  "name": "NOT_FOUND",
  "message": "The payment request ID provided by you does not exist. Please enter a valid one and try again.",
  "status": 404,
  "errors": []
}

{
  "name": "METHOD_NOT_ALLOWED",
  "message": "Refunds are not available for this account. Please contact support.",
  "status": 405,
  "errors": []
}

POST

api

refund

Initiate Refund | Refunds API

curl --request POST \
  --url https://api.atoa.me/api/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentRequestId": "<string>",
  "amount": 123,
  "currency": "<string>",
  "refundNotes": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.atoa.me/api/refund"

payload = {
    "paymentRequestId": "<string>",
    "amount": 123,
    "currency": "<string>",
    "refundNotes": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    paymentRequestId: '<string>',
    amount: 123,
    currency: '<string>',
    refundNotes: '<string>',
    metadata: {}
  })
};

fetch('https://api.atoa.me/api/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.atoa.me/api/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'paymentRequestId' => '<string>',
    'amount' => 123,
    'currency' => '<string>',
    'refundNotes' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.atoa.me/api/refund"

	payload := strings.NewReader("{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.atoa.me/api/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"paymentRequestId\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"refundNotes\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
    "refundId": "a7c82e45-9f31-42b6-8d15-7e63f1b92c4d",
    "paymentRequestId": "5e8b2c73-1f64-4a97-9c38-d2f6ae15b8c2",
    "paymentIdempotencyId": "ATOA1234567890123",
    "status": "INITIATED",
    "paidAmount": "250.75",
    "refundAmount": "25.50",
    "currency": "GBP",
    "refundNotes": "Customer requested refund",
    "orderId": "987654321",
    "createdAt": "2023-11-15T14:32:45.789Z",
    "updatedAt": "2023-11-15T14:32:45.789Z"
}

{
  "name": "BadRequestException",
  "message": "Refund amount exceeded"
}

{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": []
}

{
  "name": "NOT_FOUND",
  "message": "The payment request ID provided by you does not exist. Please enter a valid one and try again.",
  "status": 404,
  "errors": []
}

{
  "name": "METHOD_NOT_ALLOWED",
  "message": "Refunds are not available for this account. Please contact support.",
  "status": 405,
  "errors": []
}

Instant refunds are only available for selected merchants with same day payout functionality. Please reach out to support if you want to enable refunds in your account.

This API creates a refund for a specific successful payment. The refunded amount is credited to the customer’s source bank account via a bank transfer within 30 minutes, provided that you have sufficient balance available in your account. Refund can be either full or partial.

Authorization

Bearer <token>

Request Body Schema

string

required

The payment request ID of the transaction that needs to be refunded. Only completed payments can be refunded.
Note: If you need to know how to generate a payment request ID, refer to Process payment .

number

required

Amount to be refunded (should not exceed the original transaction amount). Decimal values are allowed. Minimum value is 1.

string

The currency of the refund amount. If not specified, the currency of the original transaction will be used. Example: “GBP”.

string

Refund reason for your internal reference.

To simulate a FAILED refund in sandbox environment you can pass a note with FAILURE TEST

object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Up to 50 key-value pairs.
Each key must be 1–40 characters and must not contain [ or ].
Each value must be a string of at most 500 characters.

Once set, metadata is returned in the Get Refunds response, and is included in the Refund Status Webhook.

The refund’s metadata is independent of the payment’s — it is not inherited. Metadata is frozen when the refund is created and cannot be changed afterwards. An empty object ({}) is treated as no metadata.

Response

string

The unique identifier for the refund transaction. You can use this ID to cancel the refund later via the Cancel Refund API.

string

The ID of the original payment request that is being refunded.

string

The idempotency ID of the original payment, used to ensure the payment was processed only once.

string

The current status of the refund request (e.g., “INITIATED”, “COMPLETED”, “FAILED”).

string

The original amount that was paid in the transaction being refunded.

string

The amount being refunded to the customer.

string

The currency code for the refund transaction (e.g., “GBP”).

string

Notes or reason provided for the refund.

string

The order ID associated with the original transaction.

string

The timestamp when this refund request was last updated.

string

The timestamp when this refund request was created in the system.

{
    "refundId": "a7c82e45-9f31-42b6-8d15-7e63f1b92c4d",
    "paymentRequestId": "5e8b2c73-1f64-4a97-9c38-d2f6ae15b8c2",
    "paymentIdempotencyId": "ATOA1234567890123",
    "status": "INITIATED",
    "paidAmount": "250.75",
    "refundAmount": "25.50",
    "currency": "GBP",
    "refundNotes": "Customer requested refund",
    "orderId": "987654321",
    "createdAt": "2023-11-15T14:32:45.789Z",
    "updatedAt": "2023-11-15T14:32:45.789Z"
}

{
  "name": "BadRequestException",
  "message": "Refund amount exceeded"
}

{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": []
}

{
  "name": "NOT_FOUND",
  "message": "The payment request ID provided by you does not exist. Please enter a valid one and try again.",
  "status": 404,
  "errors": []
}

{
  "name": "METHOD_NOT_ALLOWED",
  "message": "Refunds are not available for this account. Please contact support.",
  "status": 405,
  "errors": []
}

Overview

Reference

Webhook

Card on File

Initiate Refund | Refunds API

Authorization

Request Body Schema

Response

​Authorization

​Request Body Schema

​Response

Authorization

Request Body Schema

Response