curl --request POST \
--url https://api.atoa.me/api/customers/{customerId}/cards/authorize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}'
import requests
url = "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload = {
"sendLinkToCustomer": False,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": {"internalId": "42"}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch(
"https://api.atoa.me/api/customers/{customerId}/cards/authorize",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
sendLinkToCustomer: false,
successRedirectUrl: "https://yoursite.com/cards/success",
failureRedirectUrl: "https://yoursite.com/cards/failure",
metadata: { internalId: "42" },
}),
}
);
const data = await response.json();
console.log(data);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.atoa.me/api/customers/{customerId}/cards/authorize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
"sendLinkToCustomer" => false,
"successRedirectUrl" => "https://yoursite.com/cards/success",
"failureRedirectUrl" => "https://yoursite.com/cards/failure",
"metadata" => ["internalId" => "42"]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload := strings.NewReader(`{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/customers/{customerId}/cards/authorize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\"sendLinkToCustomer\":false,\"successRedirectUrl\":\"https://yoursite.com/cards/success\",\"failureRedirectUrl\":\"https://yoursite.com/cards/failure\",\"metadata\":{\"internalId\":\"42\"}}")
.asString();
{
"hostedPageUrl": "https://atoa.me/add-card?...",
"metadata": { "internalId": "42" }
}
{
"name": "BAD_REQUEST",
"message": "customerId must be a valid UUID.",
"status": 400,
"errors": []
}
{
"name": "NOT_FOUND",
"message": "Customer not found",
"status": 404,
"errors": []
}
Card on File
Authorize Card | Card on File API
Use Atoa’s Authorize Card API to securely save customer cards for future payments. Complete 3DS verification via a PCI-compliant hosted page.
POST
/
api
/
customers
/
{customerId}
/
cards
/
authorize
curl --request POST \
--url https://api.atoa.me/api/customers/{customerId}/cards/authorize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}'
import requests
url = "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload = {
"sendLinkToCustomer": False,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": {"internalId": "42"}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch(
"https://api.atoa.me/api/customers/{customerId}/cards/authorize",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
sendLinkToCustomer: false,
successRedirectUrl: "https://yoursite.com/cards/success",
failureRedirectUrl: "https://yoursite.com/cards/failure",
metadata: { internalId: "42" },
}),
}
);
const data = await response.json();
console.log(data);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.atoa.me/api/customers/{customerId}/cards/authorize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
"sendLinkToCustomer" => false,
"successRedirectUrl" => "https://yoursite.com/cards/success",
"failureRedirectUrl" => "https://yoursite.com/cards/failure",
"metadata" => ["internalId" => "42"]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload := strings.NewReader(`{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/customers/{customerId}/cards/authorize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\"sendLinkToCustomer\":false,\"successRedirectUrl\":\"https://yoursite.com/cards/success\",\"failureRedirectUrl\":\"https://yoursite.com/cards/failure\",\"metadata\":{\"internalId\":\"42\"}}")
.asString();
{
"hostedPageUrl": "https://atoa.me/add-card?...",
"metadata": { "internalId": "42" }
}
{
"name": "BAD_REQUEST",
"message": "customerId must be a valid UUID.",
"status": 400,
"errors": []
}
{
"name": "NOT_FOUND",
"message": "Customer not found",
"status": 404,
"errors": []
}
Save a customer’s card for future charges without taking a payment. Atoa returns a secure hosted page link — the customer enters their card details and completes 3DS verification, and the card is stored against their customer profile, ready to charge later.
Request Body Schema
All fields are optional — an empty body
Response
After the customer completes the hosted page flow, retrieve the saved card with List Payment Methods and use its
No amount is involved and no money moves. The customer sees a 3DS verification, not a payment. Money moves only when you call Charge Saved Card.
Card details are captured exclusively on Atoa’s PCI-compliant hosted page — they never touch your systems. Each call generates a fresh single-purpose link; request a new one rather than reusing old links.
Authorization
Bearer<accessSecret>
Path Parameters
string
required
The Atoa customer UUID returned by the Create Customer API. This is not your own merchant reference for the customer.
{} is valid.
boolean
default:"false"
When
true, Atoa delivers the link to the customer by email; if the customer has no email, by SMS. The link is also returned in the response either way. Fails with 400 if the customer has neither an email address nor a phone number.string
Where the hosted page redirects the customer after the card is saved successfully.
string
Where the hosted page redirects the customer if saving the card fails.
object
Your own key-value pairs to attach to the saved card.
- Up to 50 key-value pairs.
- Each key must be 1–40 characters and must not contain
[or]. - Each value must be a string of at most 500 characters.
string
Secure hosted page URL. Open it in a browser, embed it in a WebView, or share it with the customer. Once they complete card entry and 3DS, the card is saved — there is no separate confirmation call to make.
object
The metadata you supplied on this request, echoed back so you can confirm what will be attached to the saved card.
id as paymentMethodId when charging.
curl --request POST \
--url https://api.atoa.me/api/customers/{customerId}/cards/authorize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}'
import requests
url = "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload = {
"sendLinkToCustomer": False,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": {"internalId": "42"}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch(
"https://api.atoa.me/api/customers/{customerId}/cards/authorize",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
sendLinkToCustomer: false,
successRedirectUrl: "https://yoursite.com/cards/success",
failureRedirectUrl: "https://yoursite.com/cards/failure",
metadata: { internalId: "42" },
}),
}
);
const data = await response.json();
console.log(data);
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.atoa.me/api/customers/{customerId}/cards/authorize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
"sendLinkToCustomer" => false,
"successRedirectUrl" => "https://yoursite.com/cards/success",
"failureRedirectUrl" => "https://yoursite.com/cards/failure",
"metadata" => ["internalId" => "42"]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.atoa.me/api/customers/{customerId}/cards/authorize"
payload := strings.NewReader(`{
"sendLinkToCustomer": false,
"successRedirectUrl": "https://yoursite.com/cards/success",
"failureRedirectUrl": "https://yoursite.com/cards/failure",
"metadata": { "internalId": "42" }
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/customers/{customerId}/cards/authorize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\"sendLinkToCustomer\":false,\"successRedirectUrl\":\"https://yoursite.com/cards/success\",\"failureRedirectUrl\":\"https://yoursite.com/cards/failure\",\"metadata\":{\"internalId\":\"42\"}}")
.asString();
{
"hostedPageUrl": "https://atoa.me/add-card?...",
"metadata": { "internalId": "42" }
}
{
"name": "BAD_REQUEST",
"message": "customerId must be a valid UUID.",
"status": 400,
"errors": []
}
{
"name": "NOT_FOUND",
"message": "Customer not found",
"status": 404,
"errors": []
}