Charge API

Once you have successfully tokenized a card, you are ready to create your first payment. To do this, you make use of our API from your application's backend.

The Charge API should only be called from your server. This flow ensures the security of your payments and provides a trusted result to your server.

Request

https://online.yoco.com/v1/charges/

Headers

ParameterTypeDescription
X-Auth-Secret-Key
string
The secret key for your account

Body

ParameterTypeDescription
token
string
token generated on the frontend.
eg: tok_DgfdsVFvfbvwjkhdbxv
amountInCents
integer
A positive integer representing the amount in cents.
currency
string
An ISO 4217 currency code.
metadata
json
A set of key-value pairs that you can attach to a Charge object.

Example

import json
import requests
# Anonymous test key. Replace with your key.
SECRET_KEY = 'sk_test_960bfde0VBrLlpK098e4ffeb53e1'
response = requests.post(
'https://online.yoco.com/v1/charges/',
headers={
'X-Auth-Secret-Key': SECRET_KEY,
},
json={
'token': 'tok_test_DjaqoUgmzwYkwesr3euMxyUV4g',
'amountInCents': 2799,
'currency': 'ZAR',
},
)
# response.status_code will contain the HTTP status code
# response.json() will contain the response body

Response

Since the card details have already been checked and any 3D Secure steps have already been performed, the vast majority of requests to charge a transaction will be successful.

HTTP: 201 Created
{
"source": {
"id": "card_Aj9RzUkGWYKDaMt0M1s5XbC2zA",
"brand": "visa",
"maskedCard": "**** **** **** 4242",
"expiryMonth": 4,
"expiryYear": 2024,
"fingerprint": "09634a43594b4af0eae0a74be89df8545b29af0d",
"object": "card",
"country": "GB"
},
"object": "charge",
"id": "ch_awLYujNDMwzorIBO1iQkrikLq",
"status": "successful",
"currency": "ZAR",
"amountInCents": 2799,
"liveMode": false,
"metadata": {"your metadata object":"that you sent us"}
}