MENU navbar-image

Introduction

One by Wonderful: Public API Documentation

This documentation aims to provide all the information you need to work with our API.

As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile). You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).

Rate limiting

Please Note: If you expect to process more than 1,000 transactions per month using the API, or more than 100 transactions in any 1-hour period, we ask that you open a support ticket or email [email protected] so that we can upgrade your account to avoid rate limiting.

WooCommerce

If you are using the WooCommerce eCommerce plugin for WordPress we have a dedicated Wonderful Payments for WooCommerce plugin available to download from the WordPress plugin directory.

Authenticating API requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Generating your API token

You can generate your bearer token by visiting your Merchant dashboard. Select "Integrations" from the left navigation menu, then "API". You will be asked for the URL of your production website, then click Generate token. This is your private API token and we highly recommend you do not store it anywhere it may be shown publicly, including within source code repositories or HTML code within the browser.

You will require a new token for each production URL you wish to register. If you require more than one token please open a support ticket or email [email protected].

Endpoints

Customers

List Customers

requires authentication

List customers for the merchant. Supports basic searching on name and email address, ordering of results, and pagination. Default pagination is 25 results per page.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/customers?search=john.testmore%40example.com&sort=last_name_asc&start_date=2023-07-01&end_date=2023-12-31&per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/customers"
);

const params = {
    "search": "[email protected]",
    "sort": "last_name_asc",
    "start_date": "2023-07-01",
    "end_date": "2023-12-31",
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/customers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'search' => '[email protected]',
            'sort' => 'last_name_asc',
            'start_date' => '2023-07-01',
            'end_date' => '2023-12-31',
            'per_page' => '10',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/customers'
params = {
  'search': '[email protected]',
  'sort': 'last_name_asc',
  'start_date': '2023-07-01',
  'end_date': '2023-12-31',
  'per_page': '10',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "data": [
        {
            "id": "",
            "first_name": "Terry",
            "last_name": null,
            "full_name": "Terry",
            "email": "[email protected]",
            "address": "6443 Weimann Squares",
            "telephone": "+1-317-265-8763",
            "marketing_consented_at": null,
            "created_at": null,
            "updated_at": null
        },
        {
            "id": "",
            "first_name": "Derrick",
            "last_name": null,
            "full_name": "Derrick",
            "email": "[email protected]",
            "address": "734 Reilly Lock Suite 222",
            "telephone": "1-209-417-1194",
            "marketing_consented_at": null,
            "created_at": null,
            "updated_at": null
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": "25",
        "to": 2
    }
}

Example response (200):


{
    "data": [
        {
            "id": "1d368e62",
            "first_name": "John",
            "last_name": "Testmore",
            "full_name": "John Testmore",
            "email": "[email protected]",
            "address": "1 Test Street, Test Town",
            "telephone": "0123456789",
            "marketing_consented_at": null,
            "created_at": "2023-05-02T22:07:21.000000Z",
            "updated_at": "2023-05-02T22:07:21.000000Z"
        }
    ],
    "links": {
        "first": "https://api.wonderful.one/v2/customers?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.wonderful.one/v2/customers",
        "per_page": 25,
        "to": 1
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/customers

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

search   string  optional  

Filter customer results by name or email. Example: "John" or "[email protected]". Example: [email protected]

sort   string  optional  

Order results by column. Example: last_name_asc

Must be one of:
  • created_asc
  • created_desc
  • first_name_asc
  • first_name_desc
  • last_name_asc
  • last_name_desc
  • last_order_asc
  • last_order_desc
start_date   string  optional  

Start date in yyyy-mm-dd format. Must be a valid date. Example: 2023-07-01

end_date   string  optional  

End date in yyyy-mm-dd format. Must be a valid date. Example: 2023-12-31

per_page   integer  optional  

Number of results per page. Default: 25. Must be at least 1. Must not be greater than 1000. Example: 10

Response

Response Fields

id   string   

Public API Hash ID of the Customer

first_name   string   

Customer's first name. Example: John

last_name   string   

Customer's last name. Example: Testmore

full_name   string   

Customer's full name. Example: John Testmore

email   string   

Customer's email address. Example: [email protected]

address   string   

Customer's address. Example: 1 Test Street, Test Town

telephone   string   

Customer's telephone number. Example: 0123456789

marketing_consented_at   string   

nullable The date and time the Customer last opted in to marketing. Example: 2023-05-02T22:07:21.000000Z

created_at   string   

The date and time the Customer was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the Customer was last updated. Example: 2023-05-02T22:07:21.000000Z

Create Customer

requires authentication

Inserts a new customer record.

Example request:
curl --request POST \
    "https://api.wonderful.one/v2/customers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"first_name\": \"John\",
    \"last_name\": \"Smith\",
    \"email\": \"[email protected]\",
    \"telephone\": \"01234 567890\",
    \"address\": \"123 Some Street, London, UK\",
    \"marketing_consent\": true
}"

const url = new URL(
    "https://api.wonderful.one/v2/customers"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "telephone": "01234 567890",
    "address": "123 Some Street, London, UK",
    "marketing_consent": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/customers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'first_name' => 'John',
            'last_name' => 'Smith',
            'email' => '[email protected]',
            'telephone' => '01234 567890',
            'address' => '123 Some Street, London, UK',
            'marketing_consent' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/customers'
payload = {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "telephone": "01234 567890",
    "address": "123 Some Street, London, UK",
    "marketing_consent": true
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "",
        "first_name": "Samanta",
        "last_name": null,
        "full_name": "Samanta",
        "email": "[email protected]",
        "address": "222 Wisoky Extensions Suite 092",
        "telephone": "689-919-2730",
        "marketing_consented_at": null,
        "created_at": null,
        "updated_at": null
    }
}

Example response (201, Created successfully):


{
    "data": {
        "id": "1d368e62",
        "first_name": "John",
        "last_name": "Testmore",
        "full_name": "John Testmore",
        "email": "[email protected]",
        "address": "1 Test Street, Test Town",
        "telephone": "0123456789",
        "marketing_consented_at": null,
        "created_at": "2023-05-02T22:07:21.000000Z",
        "updated_at": "2023-05-02T22:07:21.000000Z"
    }
}

Example response (422, Validation error):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "email": [
            "The email field is required."
        ]
    }
}

Request   

POST v2/customers

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

first_name   string  optional  

Customer first (given) name. Must not be greater than 255 characters. Example: John

last_name   string  optional  

Customer last (family) name. Must not be greater than 255 characters. Example: Smith

email   string   

Customer email address. Must be a valid email address. Must not be greater than 255 characters. Example: [email protected]

telephone   string  optional  

Customer Telephone number. Must not be greater than 255 characters. Example: 01234 567890

address   string  optional  

Customer Address. Must not be greater than 255 characters. Example: 123 Some Street, London, UK

marketing_consent   boolean  optional  

Customer has opted in to marketing. Example: true

Response

Response Fields

id   string   

Public API Hash ID of the Customer

first_name   string   

Customer's first name. Example: John

last_name   string   

Customer's last name. Example: Testmore

full_name   string   

Customer's full name. Example: John Testmore

email   string   

Customer's email address. Example: [email protected]

address   string   

Customer's address. Example: 1 Test Street, Test Town

telephone   string   

Customer's telephone number. Example: 0123456789

marketing_consented_at   string   

nullable The date and time the Customer last opted in to marketing. Example: 2023-05-02T22:07:21.000000Z

created_at   string   

The date and time the Customer was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the Customer was last updated. Example: 2023-05-02T22:07:21.000000Z

Show Customer

requires authentication

Show the details of a specific customer record. Pass the Public API Hash ID of the customer you want to retrieve on the URL.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/customers/1d368e62" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/customers/1d368e62"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/customers/1d368e62';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/customers/1d368e62'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "",
        "first_name": "Tara",
        "last_name": null,
        "full_name": "Tara",
        "email": "[email protected]",
        "address": "227 Marcel Underpass",
        "telephone": "651-832-6809",
        "marketing_consented_at": null,
        "created_at": null,
        "updated_at": null
    }
}

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "first_name": "John",
        "last_name": "Testmore",
        "full_name": "John Testmore",
        "email": "[email protected]",
        "address": "1 Test Street, Test Town",
        "telephone": "0123456789",
        "marketing_consented_at": null,
        "created_at": "2023-05-02T22:07:21.000000Z",
        "updated_at": "2023-05-02T22:07:21.000000Z"
    }
}

Example response (404, Customer not found):


{
    "error": true,
    "message": "Customer not found"
}

Request   

GET v2/customers/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the customer. Example: 1d368e62

Response

Response Fields

id   string   

Public API Hash ID of the Customer

first_name   string   

Customer's first name. Example: John

last_name   string   

Customer's last name. Example: Testmore

full_name   string   

Customer's full name. Example: John Testmore

email   string   

Customer's email address. Example: [email protected]

address   string   

Customer's address. Example: 1 Test Street, Test Town

telephone   string   

Customer's telephone number. Example: 0123456789

marketing_consented_at   string   

nullable The date and time the Customer last opted in to marketing. Example: 2023-05-02T22:07:21.000000Z

created_at   string   

The date and time the Customer was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the Customer was last updated. Example: 2023-05-02T22:07:21.000000Z

Update Customer

requires authentication

Note: Pushing an update to a customer record will update the entire entity, so you must pass all the fields including those that have not been changed.

Example request:
curl --request PUT \
    "https://api.wonderful.one/v2/customers/1d368e62" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"first_name\": \"John\",
    \"last_name\": \"Smith\",
    \"email\": \"[email protected]\",
    \"telephone\": \"01234 567890\",
    \"address\": \"123 Some Street, London, UK\",
    \"marketing_consent\": true
}"

const url = new URL(
    "https://api.wonderful.one/v2/customers/1d368e62"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "telephone": "01234 567890",
    "address": "123 Some Street, London, UK",
    "marketing_consent": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/customers/1d368e62';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'first_name' => 'John',
            'last_name' => 'Smith',
            'email' => '[email protected]',
            'telephone' => '01234 567890',
            'address' => '123 Some Street, London, UK',
            'marketing_consent' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/customers/1d368e62'
payload = {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "telephone": "01234 567890",
    "address": "123 Some Street, London, UK",
    "marketing_consent": true
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "",
        "first_name": "Pat",
        "last_name": null,
        "full_name": "Pat",
        "email": "[email protected]",
        "address": "97159 Antonetta Rest",
        "telephone": "(979) 392-1698",
        "marketing_consented_at": null,
        "created_at": null,
        "updated_at": null
    }
}

Example response (200, Updated successfully):


{
    "data": {
        "id": "1d368e62",
        "first_name": "John",
        "last_name": "Testmore",
        "full_name": "John Testmore",
        "email": "[email protected]",
        "address": "1 Test Street, Test Town",
        "telephone": "0123456789",
        "marketing_consented_at": null,
        "created_at": "2023-05-02T22:07:21.000000Z",
        "updated_at": "2023-05-02T22:07:21.000000Z"
    }
}

Example response (422, Validation error):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "email": [
            "The email field is required."
        ]
    }
}

Request   

PUT v2/customers/{id}

PATCH v2/customers/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the customer. Example: 1d368e62

Body Parameters

first_name   string  optional  

Customer first (given) name. Must not be greater than 255 characters. Example: John

last_name   string  optional  

Customer last (family) name. Must not be greater than 255 characters. Example: Smith

email   string   

Customer email address. Must be a valid email address. Must not be greater than 255 characters. Example: [email protected]

telephone   string  optional  

Customer Telephone number. Must not be greater than 255 characters. Example: 01234 567890

address   string  optional  

Customer Address. Must not be greater than 255 characters. Example: 123 Some Street, London, UK

marketing_consent   boolean  optional  

Customer has opted in to marketing. Example: true

Response

Response Fields

id   string   

Public API Hash ID of the Customer

first_name   string   

Customer's first name. Example: John

last_name   string   

Customer's last name. Example: Testmore

full_name   string   

Customer's full name. Example: John Testmore

email   string   

Customer's email address. Example: [email protected]

address   string   

Customer's address. Example: 1 Test Street, Test Town

telephone   string   

Customer's telephone number. Example: 0123456789

marketing_consented_at   string   

nullable The date and time the Customer last opted in to marketing. Example: 2023-05-02T22:07:21.000000Z

created_at   string   

The date and time the Customer was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the Customer was last updated. Example: 2023-05-02T22:07:21.000000Z

Delete Customer

requires authentication

The delete customer endpoint will "soft-delete" a customer record. There is no mechanism via the API to restore a deleted record, if you need to restore a previously deleted record you will need to contact the support team.

Note that a successful delete will return a HTTP 204 with an empty response body. Attempting to delete an already deleted record will return a HTTP 404 "not found" response.

Example request:
curl --request DELETE \
    "https://api.wonderful.one/v2/customers/1d368e62" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/customers/1d368e62"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/customers/1d368e62';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/customers/1d368e62'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Example response (204, Customer deleted):

Empty response

Example response (403, Customer has orders):


{
    "error": true,
    "message": "Cannot delete customer with orders"
}

Example response (404, Customer not found):


{
    "error": true,
    "message": "Customer not found"
}

Request   

DELETE v2/customers/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the customer. Example: 1d368e62

Orders

Create an Order Refund

requires authentication

You can create a refund for an existing order. The total of all pending and completed refunds cannot exceed the amount of the original payment on the order.

NOTE: In some cases we might not be able to refund an order. In most cases this is because the customers bank did not provide us with their account details at the time of payment. In this situation the merchant should make arrangements to process the refund offline.

Example request:
curl --request POST \
    "https://api.wonderful.one/v2/orders/culpa/refund" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"refund_amount\": 1234,
    \"reference\": \"REFUND-1234\",
    \"reason\": \"Item returned, too big.\"
}"

const url = new URL(
    "https://api.wonderful.one/v2/orders/culpa/refund"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "refund_amount": 1234,
    "reference": "REFUND-1234",
    "reason": "Item returned, too big."
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/orders/culpa/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'refund_amount' => 1234,
            'reference' => 'REFUND-1234',
            'reason' => 'Item returned, too big.',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/orders/culpa/refund'
payload = {
    "refund_amount": 1234,
    "reference": "REFUND-1234",
    "reason": "Item returned, too big."
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "ed6d3864",
        "order_id": "1d679976",
        "refund_amount": 2000,
        "refund_amount_formatted": "£20.00",
        "status": "created",
        "reference": "ORDER-550433-R",
        "reason": "Item was damaged, part credit issued.",
        "created_at": "2024-04-15T15:43:34.000000Z",
        "updated_at": "2024-04-15T15:43:34.000000Z"
    }
}

Example response (200, Refund created):


{
    "data": {
        "id": "3ed6d864",
        "order_id": "1d679976",
        "refund_amount": 500,
        "refund_amount_formatted": "£5.00",
        "status": "created",
        "reference": "R1712588746",
        "reason": "Item returned, too big",
        "created_at": "2024-04-08T15:05:46.000000Z",
        "updated_at": "2024-04-08T15:05:46.000000Z"
    }
}

Example response (400, Validation error):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "refund_amount": [
            "Refund amount cannot exceed remaining amount refundable"
        ]
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Example response (404, Order not found):


{
    "error": true,
    "message": "Order not found"
}

Request   

POST v2/orders/{id}/refund

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the Order record. Example: culpa

Body Parameters

refund_amount   integer   

Refund amount in base currency units (GB Pence). Must be at least 5. Example: 1234

reference   string  optional  

Merchant payment reference to show on the bank statement. Must not be greater than 18 characters. Example: REFUND-1234

reason   string  optional  

Internal note for the refund reason (not shown to customer). Must not be greater than 255 characters. Example: Item returned, too big.

Response

Response Fields

id   string   

Public API Hash ID of the Refund. Example: 3ed6d864

order_id   string   

Public API Hash ID of the Order. Example: 3ed6d864

refund_amount   integer   

The refund amount in base currency units (GB Pence). Example: 1000

refund_amount_formatted   string   

The refund amount as a formatted currency string. Example: £10.00

status   string   

The status of the Refund. Example: paid

reference   string   

The reference of the Refund. Example: ONE-3ed6

reason   string   

The reason for the Refund (not to be shown to customers!). Example: ONE-3ed6

created_at   string   

The date and time the Refund was created. Example: 2024-04-05T14:19:58.000000Z

updated_at   string   

The date and time the Refund was last updated. Example: 2024-04-05T14:19:58.000000Z

List Orders

requires authentication

List all orders associated with the merchant. Supports basic searching on customer name and email address, ordering of results, and pagination. Default pagination is 25 results per page.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/orders?search=Smith&sort=amount_desc&payment_status=paid&start_date=2023-01-01&end_date=2023-12-31&per_page=100" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/orders"
);

const params = {
    "search": "Smith",
    "sort": "amount_desc",
    "payment_status": "paid",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "per_page": "100",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/orders';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'search' => 'Smith',
            'sort' => 'amount_desc',
            'payment_status' => 'paid',
            'start_date' => '2023-01-01',
            'end_date' => '2023-12-31',
            'per_page' => '100',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/orders'
params = {
  'search': 'Smith',
  'sort': 'amount_desc',
  'payment_status': 'paid',
  'start_date': '2023-01-01',
  'end_date': '2023-12-31',
  'per_page': '100',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "data": [
        {
            "id": "",
            "total": 72312,
            "total_formatted": "£723.12",
            "order_status": "pending",
            "amount_refundable": 0,
            "amount_pending_refund": 0,
            "amount_refunded": 0,
            "ordered_at": "2024-10-28T00:12:37.000000Z",
            "updated_at": null,
            "created_at": null,
            "payments": [],
            "refunds": []
        },
        {
            "id": "",
            "total": 70589,
            "total_formatted": "£705.89",
            "order_status": "pending",
            "amount_refundable": 0,
            "amount_pending_refund": 0,
            "amount_refunded": 0,
            "ordered_at": "2024-11-21T08:11:54.000000Z",
            "updated_at": null,
            "created_at": null,
            "payments": [],
            "refunds": []
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": "25",
        "to": 2
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/orders

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

search   string  optional  

Filter orders by customer first name, last name, or email. Example: "Smith" or "[email protected]". Must not be greater than 255 characters. Example: Smith

sort   string  optional  

Order results by column. Example: amount_desc

Must be one of:
  • created_asc
  • created_desc
  • amount_asc
  • amount_desc
payment_status   string  optional  

Filter orders by payment status. Example: paid

Must be one of:
  • created
  • pending
  • paid
  • failed
  • cancelled
  • part-refunded
  • refunded
  • expired
start_date   string  optional  

Start date in yyyy-mm-dd format. Must be a valid date. Example: 2023-01-01

end_date   string  optional  

End date in yyyy-mm-dd format. Must be a valid date. Example: 2023-12-31

per_page   integer  optional  

Number of results per page. Default: 25. Must be at least 1. Must not be greater than 1000. Example: 100

Response

Response Fields

id   string   

The public API hash ID of the Order.

total   integer   

The total amount of the Order in base currency units (GB Pence).

total_formatted   string   

The total amount of the Order as a formatted currency string.

order_status   string   

The status of the Order.

amount_refundable   integer   

The total amount of the Order that is refundable in base currency units.

amount_pending_refund   integer   

The total amount of the Order currently pending refund in base currency units.

amount_refunded   integer   

The total amount of the Order that has been refunded in base currency units.

ordered_at   string   

The date and time the Order was ordered.

updated_at   string   

The date and time the Order was last updated.

created_at   string   

The date and time the Order was created on the system.

customer   object   

The Customer record associated with the Order.

payments   object[]   

All Payment records associated with the Order.

order_lines   object[]   

All OrderLine records associated with the Order.

Show Order

requires authentication

Shows the specific details for a single order.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/orders/culpa" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/orders/culpa"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/orders/culpa';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/orders/culpa'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "",
        "total": 21240,
        "total_formatted": "£212.40",
        "order_status": "pending",
        "amount_refundable": 0,
        "amount_pending_refund": 0,
        "amount_refunded": 0,
        "ordered_at": "2024-06-13T05:41:54.000000Z",
        "updated_at": null,
        "created_at": null,
        "payments": [],
        "refunds": []
    }
}

Example response (200, Order found):


{
    "data": {
        "id": "ed6d3016",
        "total": 8957,
        "total_formatted": "£89.57",
        "order_status": "pending",
        "ordered_at": "2024-03-05T11:50:43.000000Z",
        "updated_at": "2024-03-05T11:50:43.000000Z",
        "created_at": "2024-03-05T11:50:43.000000Z",
        "customer": {
            "id": "89650465",
            "first_name": null,
            "last_name": null,
            "full_name": "",
            "email": "[email protected]",
            "address": null,
            "telephone": null,
            "marketing_consented_at": null,
            "created_at": "2024-03-05T11:50:43.000000Z",
            "updated_at": "2024-03-05T11:50:43.000000Z"
        },
        "payments": [
            {
                "id": "ed6d3016",
                "order_id": "ed6d3016",
                "amount": 8957,
                "amount_formatted": "£89.57",
                "status": "created",
                "reference": "ORDER-DE81",
                "pay_link": "https://api.wonderful.one/pay/DE81",
                "created_at": "2024-03-05T11:50:43.000000Z",
                "updated_at": "2024-03-05T11:50:43.000000Z"
            }
        ],
        "order_lines": [
            {
                "id": "ed6d87e6",
                "order_id": "ed6d3016",
                "quantity": 1,
                "description": "Gorgeous Fresh Soap",
                "price": 8957,
                "price_formatted": "£89.57",
                "created_at": "2024-03-05T11:50:43.000000Z",
                "updated_at": "2024-03-05T11:50:43.000000Z"
            }
        ]
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Example response (404, Order not found):


{
    "error": true,
    "message": "Order not found"
}

Request   

GET v2/orders/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the Payment record. Example: culpa

Response

Response Fields

id   string   

The public API hash ID of the Order.

total   integer   

The total amount of the Order in base currency units (GB Pence).

total_formatted   string   

The total amount of the Order as a formatted currency string.

order_status   string   

The status of the Order.

amount_refundable   integer   

The total amount of the Order that is refundable in base currency units.

amount_pending_refund   integer   

The total amount of the Order currently pending refund in base currency units.

amount_refunded   integer   

The total amount of the Order that has been refunded in base currency units.

ordered_at   string   

The date and time the Order was ordered.

updated_at   string   

The date and time the Order was last updated.

created_at   string   

The date and time the Order was created on the system.

customer   object   

The Customer record associated with the Order.

payments   object[]   

All Payment records associated with the Order.

order_lines   object[]   

All OrderLine records associated with the Order.

Payments

Quick Pay

requires authentication

The Quick Pay endpoint allows you to create a customer, order, order line, and payment in one request. The minimum data required is the amount and a merchant payment reference (which is shown on the customer's bank statement). If you also provide a customer email address, the order will be linked to the customer record.

Example request:
curl --request POST \
    "https://api.wonderful.one/v2/quick-pay" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1234,
    \"merchant_payment_reference\": \"ORDER-1234\",
    \"payment_description\": \"Website Order 1234\",
    \"customer_email_address\": \"[email protected]\",
    \"redirect_url\": \"https:\\/\\/your-website.example.com\\/success\",
    \"webhook_url\": \"https:\\/\\/your-website.example.com\\/webhooks\",
    \"bank_id\": \"natwest\"
}"

const url = new URL(
    "https://api.wonderful.one/v2/quick-pay"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1234,
    "merchant_payment_reference": "ORDER-1234",
    "payment_description": "Website Order 1234",
    "customer_email_address": "[email protected]",
    "redirect_url": "https:\/\/your-website.example.com\/success",
    "webhook_url": "https:\/\/your-website.example.com\/webhooks",
    "bank_id": "natwest"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/quick-pay';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 1234,
            'merchant_payment_reference' => 'ORDER-1234',
            'payment_description' => 'Website Order 1234',
            'customer_email_address' => '[email protected]',
            'redirect_url' => 'https://your-website.example.com/success',
            'webhook_url' => 'https://your-website.example.com/webhooks',
            'bank_id' => 'natwest',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/quick-pay'
payload = {
    "amount": 1234,
    "merchant_payment_reference": "ORDER-1234",
    "payment_description": "Website Order 1234",
    "customer_email_address": "[email protected]",
    "redirect_url": "https:\/\/your-website.example.com\/success",
    "webhook_url": "https:\/\/your-website.example.com\/webhooks",
    "bank_id": "natwest"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "order_id": "1d368e62",
        "amount": 33969,
        "amount_formatted": "£339.69",
        "status": "refunded",
        "can_be_refunded": 0,
        "reference": "ONE-0980",
        "pay_link": "http://wonderful-one.test/pay/0980",
        "created_at": "2023-04-19T11:48:33.000000Z",
        "updated_at": "2023-05-02T16:47:29.000000Z"
    }
}

Example response (201, Success):


{
    "data": {
        "id": "ed6d3316",
        "order_id": "ed6d3316",
        "amount": 6482,
        "amount_formatted": "£64.82",
        "status": "created",
        "reference": "ORDER-585516",
        "pay_link": "https://api.wonderful.one/pay/DEE1",
        "created_at": "2024-03-05T12:20:47.000000Z",
        "updated_at": "2024-03-05T12:20:47.000000Z"
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Example response (422, Validation failed):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "amount": [
            "The amount field is required."
        ],
        "merchant_payment_reference": [
            "The merchant payment reference field is required."
        ]
    }
}

Request   

POST v2/quick-pay

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   integer   

Amount in base currency units (GB Pence). Must be at least 5. Example: 1234

merchant_payment_reference   string   

Merchant payment reference to show on the bank statement. Must contain only letters, numbers, dashes and underscores. Must not be greater than 18 characters. Example: ORDER-1234

payment_description   string  optional  

Payment description to show against the Order record. Must not be greater than 255 characters. Example: Website Order 1234

customer_email_address   string  optional  

Customer email address. If set, this will link the Order to the Customer record. Must be a valid email address. Must not be greater than 255 characters. Example: [email protected]

redirect_url   string   

The URL to redirect to after the payment has been completed. Must be a valid URL. Example: https://your-website.example.com/success

webhook_url   string  optional  

The URL to send webhook notifications to. Must be a valid URL. Example: https://your-website.example.com/webhooks

bank_id   string  optional  

Advanced users only: Pre-select the customer bank to process the payment. Must match a bank_id from the Supported Banks endpoint. Must not be greater than 255 characters. Example: natwest

Response

Response Fields

id   string   

Public API Hash ID of the Payment. Example: 3ed6d864

order_id   string   

Public API Hash ID of the Order. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

status   string   

The status of the Payment. Example: paid

can_be_refunded   integer   

in Can the payment be refunded. 1 - Yes, 0 - No Example: 1

reference   string   

The reference of the Payment. Example: ONE-3ed6

pay_link   string   

The URL to redirect the customer to for payment. Example: https://wonderful.one/pay/abc123

created_at   string   

The date and time the Payment was created. Example: 2024-04-05T14:19:58.000000Z

updated_at   string   

The date and time the Payment was last updated. Example: 2024-04-05T14:19:58.000000Z

List Payments

requires authentication

Returns a collection of all Payment records associated with the Merchant.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/payments?search=ORDER&sort=amount_desc&start_date=2023-01-01&end_date=2023-12-31&per_page=100" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/payments"
);

const params = {
    "search": "ORDER",
    "sort": "amount_desc",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "per_page": "100",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/payments';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'search' => 'ORDER',
            'sort' => 'amount_desc',
            'start_date' => '2023-01-01',
            'end_date' => '2023-12-31',
            'per_page' => '100',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/payments'
params = {
  'search': 'ORDER',
  'sort': 'amount_desc',
  'start_date': '2023-01-01',
  'end_date': '2023-12-31',
  'per_page': '100',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "data": [
        {
            "id": "1d368e62",
            "order_id": "1d368e62",
            "amount": 33969,
            "amount_formatted": "£339.69",
            "status": "refunded",
            "can_be_refunded": 0,
            "reference": "ONE-0980",
            "pay_link": "http://wonderful-one.test/pay/0980",
            "created_at": "2023-04-19T11:48:33.000000Z",
            "updated_at": "2023-05-02T16:47:29.000000Z"
        },
        {
            "id": "1d368e62",
            "order_id": "1d368e62",
            "amount": 33969,
            "amount_formatted": "£339.69",
            "status": "refunded",
            "can_be_refunded": 0,
            "reference": "ONE-0980",
            "pay_link": "http://wonderful-one.test/pay/0980",
            "created_at": "2023-04-19T11:48:33.000000Z",
            "updated_at": "2023-05-02T16:47:29.000000Z"
        }
    ]
}

Example response (200, Filtered search, ordered by descending value):


{
    "data": [
        {
            "id": "ed6d3316",
            "order_id": "ed6d3316",
            "amount": 6482,
            "amount_formatted": "£64.82",
            "status": "created",
            "reference": "ORDER-585516",
            "pay_link": "https://api.wonderful.one/pay/DEE1",
            "created_at": "2024-03-05T12:20:47.000000Z",
            "updated_at": "2024-03-05T12:20:47.000000Z"
        },
        {
            "id": "e2610086",
            "order_id": "e2610086",
            "amount": 4765,
            "amount_formatted": "£47.65",
            "status": "created",
            "reference": "ORDER-115103",
            "pay_link": "https://api.wonderful.one/pay/8552",
            "created_at": "2024-03-05T11:58:24.000000Z",
            "updated_at": "2024-03-05T11:58:24.000000Z"
        },
        {
            "id": "05644446",
            "order_id": "05644446",
            "amount": 3058,
            "amount_formatted": "£30.58",
            "status": "created",
            "reference": "ORDER-314744",
            "pay_link": "https://api.wonderful.one/pay/6666",
            "created_at": "2024-03-05T11:58:22.000000Z",
            "updated_at": "2024-03-05T11:58:22.000000Z"
        },
        {
            "id": "d368ee26",
            "order_id": "d368ee26",
            "amount": 510,
            "amount_formatted": "£5.10",
            "status": "created",
            "reference": "ORDER-302271",
            "pay_link": "https://api.wonderful.one/pay/9887",
            "created_at": "2024-03-05T11:58:23.000000Z",
            "updated_at": "2024-03-05T11:58:23.000000Z"
        }
    ],
    "links": {
        "first": "https://api.wonderful.one/v2/payments?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.wonderful.one/v2/payments",
        "per_page": "100",
        "to": 4
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/payments

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

search   string  optional  

Filter payment results by order reference. Example: "ONE" or "ABC123". Must not be greater than 255 characters. Example: ORDER

sort   string  optional  

Order results by column. Example: amount_desc

Must be one of:
  • created_asc
  • created_desc
  • amount_asc
  • amount_desc
start_date   string  optional  

Start date in yyyy-mm-dd format. Must be a valid date. Example: 2023-01-01

end_date   string  optional  

End date in yyyy-mm-dd format. Must be a valid date. Example: 2023-12-31

per_page   integer  optional  

Number of results per page. Default: 25. Must be at least 1. Must not be greater than 1000. Example: 100

Response

Response Fields

id   string   

Public API Hash ID of the Payment. Example: 3ed6d864

order_id   string   

Public API Hash ID of the Order. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

status   string   

The status of the Payment. Example: paid

can_be_refunded   integer   

in Can the payment be refunded. 1 - Yes, 0 - No Example: 1

reference   string   

The reference of the Payment. Example: ONE-3ed6

pay_link   string   

The URL to redirect the customer to for payment. Example: https://wonderful.one/pay/abc123

created_at   string   

The date and time the Payment was created. Example: 2024-04-05T14:19:58.000000Z

updated_at   string   

The date and time the Payment was last updated. Example: 2024-04-05T14:19:58.000000Z

Show Payment

requires authentication

Shows the details of a specific Payment record.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/payments/culpa" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/payments/culpa"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/payments/culpa';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/payments/culpa'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "order_id": "1d368e62",
        "amount": 33969,
        "amount_formatted": "£339.69",
        "status": "refunded",
        "can_be_refunded": 0,
        "reference": "ONE-0980",
        "pay_link": "http://wonderful-one.test/pay/0980",
        "created_at": "2023-04-19T11:48:33.000000Z",
        "updated_at": "2023-05-02T16:47:29.000000Z"
    }
}

Example response (200):


{
    "data": {
        "id": "e2611865",
        "order_id": "e2611865",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "status": "created",
        "reference": "ONE-0862",
        "pay_link": "https://api.wonderful.one/pay/0862",
        "created_at": "2023-07-07T08:59:55.000000Z",
        "updated_at": "2023-07-07T08:59:55.000000Z"
    }
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/payments/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the Payment record. Example: culpa

Response

Response Fields

id   string   

Public API Hash ID of the Payment. Example: 3ed6d864

order_id   string   

Public API Hash ID of the Order. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

status   string   

The status of the Payment. Example: paid

can_be_refunded   integer   

in Can the payment be refunded. 1 - Yes, 0 - No Example: 1

reference   string   

The reference of the Payment. Example: ONE-3ed6

pay_link   string   

The URL to redirect the customer to for payment. Example: https://wonderful.one/pay/abc123

created_at   string   

The date and time the Payment was created. Example: 2024-04-05T14:19:58.000000Z

updated_at   string   

The date and time the Payment was last updated. Example: 2024-04-05T14:19:58.000000Z

WooCommerce Payments

requires authentication

The Woo Pay endpoint allows you to create a customer, order, order line, and payment in one request. The minimum data required is the amount and a merchant payment reference (which is shown on the customer's bank statement) and the selected bank. If you also provide a customer email address, the order will be linked to the customer record.

Example request:
curl --request POST \
    "https://api.wonderful.one/v2/woo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1234,
    \"merchant_payment_reference\": \"ORDER-1234\",
    \"payment_description\": \"Website Order 1234\",
    \"customer_email_address\": \"[email protected]\",
    \"redirect_url\": \"https:\\/\\/your-website.example.com\\/success\",
    \"webhook_url\": \"https:\\/\\/your-website.example.com\\/webhooks\",
    \"bank_id\": \"natwest\",
    \"selected_aspsp\": \"pasyzwszwtxpeqq\"
}"

const url = new URL(
    "https://api.wonderful.one/v2/woo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1234,
    "merchant_payment_reference": "ORDER-1234",
    "payment_description": "Website Order 1234",
    "customer_email_address": "[email protected]",
    "redirect_url": "https:\/\/your-website.example.com\/success",
    "webhook_url": "https:\/\/your-website.example.com\/webhooks",
    "bank_id": "natwest",
    "selected_aspsp": "pasyzwszwtxpeqq"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/woo';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 1234,
            'merchant_payment_reference' => 'ORDER-1234',
            'payment_description' => 'Website Order 1234',
            'customer_email_address' => '[email protected]',
            'redirect_url' => 'https://your-website.example.com/success',
            'webhook_url' => 'https://your-website.example.com/webhooks',
            'bank_id' => 'natwest',
            'selected_aspsp' => 'pasyzwszwtxpeqq',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/woo'
payload = {
    "amount": 1234,
    "merchant_payment_reference": "ORDER-1234",
    "payment_description": "Website Order 1234",
    "customer_email_address": "[email protected]",
    "redirect_url": "https:\/\/your-website.example.com\/success",
    "webhook_url": "https:\/\/your-website.example.com\/webhooks",
    "bank_id": "natwest",
    "selected_aspsp": "pasyzwszwtxpeqq"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Request   

POST v2/woo

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   integer   

Amount in base currency units (GB Pence). Must be at least 5. Example: 1234

merchant_payment_reference   string   

Merchant payment reference to show on the bank statement. Must contain only letters, numbers, dashes and underscores. Must not be greater than 18 characters. Example: ORDER-1234

payment_description   string  optional  

Payment description to show against the Order record. Must not be greater than 255 characters. Example: Website Order 1234

customer_email_address   string  optional  

Customer email address. If set, this will link the Order to the Customer record. Must be a valid email address. Must not be greater than 255 characters. Example: [email protected]

redirect_url   string   

The URL to redirect to after the payment has been completed. Must be a valid URL. Example: https://your-website.example.com/success

webhook_url   string  optional  

The URL to send webhook notifications to. Must be a valid URL. Example: https://your-website.example.com/webhooks

bank_id   string  optional  

Advanced users only: Pre-select the customer bank to process the payment. Must match a bank_id from the Supported Banks endpoint. Must not be greater than 255 characters. Example: natwest

selected_aspsp   string   

Must not be greater than 255 characters. Example: pasyzwszwtxpeqq

Show method to retrieve payment details from Wonderful Payments service.

requires authentication

This method retrieves the authenticated user's associated merchant, and then returns the response from the Wonderful Payments service for the specified payment ID.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/woo/culpa" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/woo/culpa"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/woo/culpa';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/woo/culpa'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Request   

GET v2/woo/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The ID of the woo. Example: culpa

Generate a reference code for the authenticated merchant.

requires authentication

This method retrieves the authenticated user's associated merchant, generates a hashed reference code using Hashids, and returns it as JSON. If the authenticated user is not a merchant, it returns an error response.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/ref" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/ref"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/ref';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/ref'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Request   

GET v2/ref

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

QR Codes

List QR Codes

requires authentication

Lists all QR Codes associated with the Merchant

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/qr-codes" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/qr-codes"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/qr-codes';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/qr-codes'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": [
        {
            "id": "1d368e62",
            "amount": 1000,
            "amount_formatted": "£10.00",
            "label": "My first QR code",
            "pay_link": "http://wonderful-one.test/qr-code/e24e",
            "image_link": "http://wonderful-one.test/qr-code-image/e24e",
            "created_at": "2023-07-05T13:03:23.000000Z",
            "updated_at": "2023-07-05T13:03:23.000000Z"
        },
        {
            "id": "1d368e62",
            "amount": 1000,
            "amount_formatted": "£10.00",
            "label": "My first QR code",
            "pay_link": "http://wonderful-one.test/qr-code/e24e",
            "image_link": "http://wonderful-one.test/qr-code-image/e24e",
            "created_at": "2023-07-05T13:03:23.000000Z",
            "updated_at": "2023-07-05T13:03:23.000000Z"
        }
    ]
}

Example response (200):


{
    "data": [
        {
            "id": "1d368e62",
            "amount": 1000,
            "amount_formatted": "£10.00",
            "label": "My first QR code",
            "pay_link": "https://api.wonderful-one.test/qr-code/e24e",
            "image_link": "https://api.wonderful-one.test/qr-code-image/e24e",
            "created_at": "2023-07-05T15:03:23.000000Z",
            "updated_at": "2023-07-05T15:03:23.000000Z"
        },
        {
            "id": "0e261265",
            "amount": 1234,
            "amount_formatted": "£12.34",
            "label": "My second QR code",
            "pay_link": "https://api.wonderful-one.test/qr-code/ed4e",
            "image_link": "https://api.wonderful-one.test/qr-code-image/ed4e",
            "created_at": "2023-07-05T15:04:05.000000Z",
            "updated_at": "2023-07-05T15:04:05.000000Z"
        }
    ]
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/qr-codes

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Response

Response Fields

id   string   

Public API Hash ID of the QR Code. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

label   string   

The label of the QR Code. Example: Blue Widget

pay_link   string   

The URL to redirect the customer to for payment. Example: https://api.wonderful.one/qr-code/abc123

image_link   string   

Generated QR code image URL that will redirect the customer to the Pay Link. Example: https://api.wonderful.one/qr-code-image/abc123

created_at   string   

The date and time the QR Code was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the QR Code was last updated. Example: 2023-05-02T22:07:21.000000Z

Create QR Code

requires authentication

Inserts a new QR Code record.

Example request:
curl --request POST \
    "https://api.wonderful.one/v2/qr-codes" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1234,
    \"label\": \"Blue Widget\"
}"

const url = new URL(
    "https://api.wonderful.one/v2/qr-codes"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1234,
    "label": "Blue Widget"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/qr-codes';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 1234,
            'label' => 'Blue Widget',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/qr-codes'
payload = {
    "amount": 1234,
    "label": "Blue Widget"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "http://wonderful-one.test/qr-code/e24e",
        "image_link": "http://wonderful-one.test/qr-code-image/e24e",
        "created_at": "2023-07-05T13:03:23.000000Z",
        "updated_at": "2023-07-05T13:03:23.000000Z"
    }
}

Example response (201, Created successfully):


{
    "data": {
        "id": "0e261265",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "https://api.wonderful-one.test/qr-code/ed4e",
        "image_link": "https://api.wonderful-one.test/qr-code-image/ed4e",
        "created_at": "2023-07-05T15:04:05.000000Z",
        "updated_at": "2023-07-05T15:04:05.000000Z"
    }
}

Example response (422, Validation error):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "amount": [
            "The amount field is required."
        ],
        "label": [
            "The label field is required."
        ]
    }
}

Request   

POST v2/qr-codes

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   integer   

Amount in base currency units (GB Pence). Must not be greater than 5000000. Example: 1234

label   string   

QR Code label or description (shown to customers). Must not be greater than 255 characters. Example: Blue Widget

Response

Response Fields

id   string   

Public API Hash ID of the QR Code. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

label   string   

The label of the QR Code. Example: Blue Widget

pay_link   string   

The URL to redirect the customer to for payment. Example: https://api.wonderful.one/qr-code/abc123

image_link   string   

Generated QR code image URL that will redirect the customer to the Pay Link. Example: https://api.wonderful.one/qr-code-image/abc123

created_at   string   

The date and time the QR Code was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the QR Code was last updated. Example: 2023-05-02T22:07:21.000000Z

Show QR Code

requires authentication

Show the details of a specific QR Code record. Pass the Public API Hash ID of the QR Code you wand to retrieve on the URL.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/qr-codes/0e261265" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/qr-codes/0e261265"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/qr-codes/0e261265';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/qr-codes/0e261265'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "http://wonderful-one.test/qr-code/e24e",
        "image_link": "http://wonderful-one.test/qr-code-image/e24e",
        "created_at": "2023-07-05T13:03:23.000000Z",
        "updated_at": "2023-07-05T13:03:23.000000Z"
    }
}

Example response (200):


{
    "data": {
        "id": "0e261265",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "https://api.wonderful-one.test/qr-code/ed4e",
        "image_link": "https://api.wonderful-one.test/qr-code-image/ed4e",
        "created_at": "2023-07-05T15:04:05.000000Z",
        "updated_at": "2023-07-05T15:04:05.000000Z"
    }
}

Example response (404, QR code not found):


{
    "error": true,
    "message": "QR code not found"
}

Request   

GET v2/qr-codes/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

the Public API Hash ID of the QR Code. Example: 0e261265

Response

Response Fields

id   string   

Public API Hash ID of the QR Code. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

label   string   

The label of the QR Code. Example: Blue Widget

pay_link   string   

The URL to redirect the customer to for payment. Example: https://api.wonderful.one/qr-code/abc123

image_link   string   

Generated QR code image URL that will redirect the customer to the Pay Link. Example: https://api.wonderful.one/qr-code-image/abc123

created_at   string   

The date and time the QR Code was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the QR Code was last updated. Example: 2023-05-02T22:07:21.000000Z

Update QR Code.

requires authentication

Note: You must pass both the amount and label values even if only one of them has changed.

Example request:
curl --request PUT \
    "https://api.wonderful.one/v2/qr-codes/0e261265" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1234,
    \"label\": \"Blue Widget\"
}"

const url = new URL(
    "https://api.wonderful.one/v2/qr-codes/0e261265"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1234,
    "label": "Blue Widget"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/qr-codes/0e261265';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 1234,
            'label' => 'Blue Widget',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/qr-codes/0e261265'
payload = {
    "amount": 1234,
    "label": "Blue Widget"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "1d368e62",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "http://wonderful-one.test/qr-code/e24e",
        "image_link": "http://wonderful-one.test/qr-code-image/e24e",
        "created_at": "2023-07-05T13:03:23.000000Z",
        "updated_at": "2023-07-05T13:03:23.000000Z"
    }
}

Example response (200, Updated successfully):


{
    "data": {
        "id": "0e261265",
        "amount": 1000,
        "amount_formatted": "£10.00",
        "label": "My first QR code",
        "pay_link": "https://api.wonderful-one.test/qr-code/ed4e",
        "image_link": "https://api.wonderful-one.test/qr-code-image/ed4e",
        "created_at": "2023-07-05T15:04:05.000000Z",
        "updated_at": "2023-07-05T15:04:05.000000Z"
    }
}

Example response (422, Validation error):


{
    "error": true,
    "message": "Validation failed",
    "invalid_fields": {
        "amount": [
            "The amount field is required."
        ],
        "label": [
            "The label field is required."
        ]
    }
}

Request   

PUT v2/qr-codes/{id}

PATCH v2/qr-codes/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the QR Code. Example: 0e261265

Body Parameters

amount   integer   

Amount in base currency units (GB Pence). Must not be greater than 5000000. Example: 1234

label   string   

QR Code label or description (shown to customers). Must not be greater than 255 characters. Example: Blue Widget

Response

Response Fields

id   string   

Public API Hash ID of the QR Code. Example: 3ed6d864

amount   integer   

The amount in base currency units (GB Pence). Example: 1000

amount_formatted   string   

The amount as a formatted currency string. Example: £10.00

label   string   

The label of the QR Code. Example: Blue Widget

pay_link   string   

The URL to redirect the customer to for payment. Example: https://api.wonderful.one/qr-code/abc123

image_link   string   

Generated QR code image URL that will redirect the customer to the Pay Link. Example: https://api.wonderful.one/qr-code-image/abc123

created_at   string   

The date and time the QR Code was created. Example: 2023-05-02T22:07:21.000000Z

updated_at   string   

The date and time the QR Code was last updated. Example: 2023-05-02T22:07:21.000000Z

Delete QR Code

requires authentication

The delete QR code endpoint will "soft-delete" a QR code record. There is no mechanism via the API to restore a deleted record, if you need to restore a previously deleted record you will need to contact the support team.

Note that a successful delete will return a HTTP 204 with an empty response body. Attempting to delete an already deleted record will return a HTTP 404 "not found" response.

Example request:
curl --request DELETE \
    "https://api.wonderful.one/v2/qr-codes/0e261265" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/qr-codes/0e261265"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/qr-codes/0e261265';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/qr-codes/0e261265'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Example response (204, QR code deleted):

Empty response

Example response (404, QR code not found):


{
    "error": true,
    "message": "QR code not found"
}

Request   

DELETE v2/qr-codes/{id}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   string   

The Public API Hash ID of the QR code. Example: 0e261265

Supported Banks.

requires authentication

Some API endponts require a bank to be selected. Use this endpoint to get a list of all the currently active bank IDs, along with their display names and logos.

Example request:
curl --request GET \
    --get "https://api.wonderful.one/v2/supported-banks" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.wonderful.one/v2/supported-banks"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.wonderful.one/v2/supported-banks';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.wonderful.one/v2/supported-banks'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": [
        {
            "bank_id": "aib",
            "bank_name": "Allied Irish Bank (GB)",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/aib.png",
            "status": "online"
        },
        {
            "bank_id": "danske",
            "bank_name": "Danske Bank",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/danske.png",
            "status": "online"
        },
        {
            "bank_id": "barclays",
            "bank_name": "Barclays",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/barclays.png",
            "status": "issues"
        },
        {
            "bank_id": "monzo",
            "bank_name": "Monzo",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/monzo.png",
            "status": "online"
        },
        {
            "bank_id": "natwest",
            "bank_name": "Natwest",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/natwest.png",
            "status": "online"
        },
        {
            "bank_id": "revolut",
            "bank_name": "Revolut",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/revolut.png",
            "status": "online"
        },
        {
            "bank_id": "santander",
            "bank_name": "Santander",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/santander.png",
            "status": "issues"
        },
        {
            "bank_id": "starling",
            "bank_name": "Starling",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/starling.png",
            "status": "online"
        },
        {
            "bank_id": "tesco",
            "bank_name": "Tesco",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/tesco.png",
            "status": "online"
        },
        {
            "bank_id": "tide",
            "bank_name": "Tide",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/tide.png",
            "status": "online"
        },
        {
            "bank_id": "tsb",
            "bank_name": "TSB",
            "bank_logo": "https://wonderful.co.uk/img/bank_logos/tsb.png",
            "status": "online"
        }
    ]
}

Example response (401, Invalid auth token):


{
    "error": true,
    "message": "Unauthenticated."
}

Request   

GET v2/supported-banks

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Response

Response Fields

bank_id   string   

Bank Identifier. Example: 'bos'

bank_name   string   

Display name that can be shown to the customer. Example: 'Bank of Scotland'

bank_logo   string   

URL of the logo that can be shown to the customer. Example: https://wonderful.co.uk/img/bank_logos/bos.png

status   string   

Status of the bank. Possible values are: online, issues, offline. Example: 'online'