> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

## What's idempotency?

An API call or operation is idempotent if it always produces the same outcome, regardless of how
many times it's executed. This ensures that accidental duplicate calls don't cause unintended
consequences.

This feature is especially valuable when an API call fails due to network issues or the temporary
unavailability of Yoco's services.

## Idempotent requests using the API

The Checkout API enables idempotency by allowing API operations to include an optional unique string
as an idempotency key in an additional `Idempotency-Key` header. When the request is retried with
the same key, the API returns the same result, status code and an additional HTTP response header of
`Idempotent-Replayed` set to `true`.

The method for creating unique idempotency keys is up to you, but 128-bit keys are recommended to
avoid accidental key collisions.

If you want to keep things simple, use UUIDv4.

Replayed responses returns the status code and body of the first request made for any given
idempotency key, regardless of whether it succeeded or failed.

Keys are removed from the system automatically after 24 hours. A later request with the same key
after its expiry period is treated as a new request.

### Request

POST [https://payments.yoco.com/api/checkouts](https://payments.yoco.com/api/checkouts)

**`Checkout with idempotency key`**

```curl Checkout with idempotency key
curl -X POST https://payments.yoco.com/api/checkouts \
     -H "Idempotency-Key: 1234567890" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "amount": 10000,
  "currency": "ZAR"
}'
```

**`Checkout with idempotency key`**

```python Checkout with idempotency key
import requests

url = "https://payments.yoco.com/api/checkouts"

payload = {
    "amount": 10000,
    "currency": "ZAR"
}
headers = {
    "Idempotency-Key": "1234567890",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Checkout with idempotency key`**

```javascript Checkout with idempotency key
const url = 'https://payments.yoco.com/api/checkouts';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '1234567890',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"amount":10000,"currency":"ZAR"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Checkout with idempotency key`**

```go Checkout with idempotency key
package main

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

func main() {

	url := "https://payments.yoco.com/api/checkouts"

	payload := strings.NewReader("{\n  \"amount\": 10000,\n  \"currency\": \"ZAR\"\n}")

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

	req.Header.Add("Idempotency-Key", "1234567890")
	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(res)
	fmt.Println(string(body))

}
```

**`Checkout with idempotency key`**

```ruby Checkout with idempotency key
require 'uri'
require 'net/http'

url = URI("https://payments.yoco.com/api/checkouts")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '1234567890'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 10000,\n  \"currency\": \"ZAR\"\n}"

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

**`Checkout with idempotency key`**

```java Checkout with idempotency key
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://payments.yoco.com/api/checkouts")
  .header("Idempotency-Key", "1234567890")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 10000,\n  \"currency\": \"ZAR\"\n}")
  .asString();
```

**`Checkout with idempotency key`**

```php Checkout with idempotency key
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://payments.yoco.com/api/checkouts', [
  'body' => '{
  "amount": 10000,
  "currency": "ZAR"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '1234567890',
  ],
]);

echo $response->getBody();
```

**`Checkout with idempotency key`**

```csharp Checkout with idempotency key
using RestSharp;

var client = new RestClient("https://payments.yoco.com/api/checkouts");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "1234567890");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amount\": 10000,\n  \"currency\": \"ZAR\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Checkout with idempotency key`**

```swift Checkout with idempotency key
import Foundation

let headers = [
  "Idempotency-Key": "1234567890",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "amount": 10000,
  "currency": "ZAR"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://payments.yoco.com/api/checkouts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> **Info**
>
> Idempotency is only supported for POST requests.