curl --request POST \
--url https://api.tagada.io/api/public/v1/payment-instruments/create-from-token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tagadaToken": "eyJ0eXBlIjoiY2FyZCIsInRva2VuIjoiYnRfdG9rZW5fMTIzIiwicHJvdmlkZXIiOiJiYXNpc3RoZW9yeSIsIm5vblNlbnNpdGl2ZU1ldGFkYXRhIjp7Imxhc3Q0IjoiNDI0MiIsImJyYW5kIjoidmlzYSIsImV4cGlyeU1vbnRoIjoxMiwiZXhwaXJ5WWVhciI6MjAyNX19",
"storeId": "store_eaa20d619f6b",
"customerId": "cus_123"
}
'
{
"paymentInstrument": {
"id": "pi_123",
"type": "card",
"customerId": "cus_123",
"accountId": "acc_123",
"isActive": true,
"isDefault": false,
"tokenizer": "basistheory",
"createdAt": "2024-03-20T10:30:00Z",
"card": {
"last4": "4242",
"brand": "visa",
"expYear": 2025,
"expMonth": 12
}
},
"customer": {
"id": "cus_123",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"createdAt": "2024-03-20T10:30:00Z"
}
}
payment-instruments
Create payment instrument from TagadaToken
Create a payment instrument from a base64 encoded TagadaToken. This endpoint decodes the TagadaToken and extracts the necessary payment information to create a payment instrument.
The TagadaToken should contain:
- type: ‘card’
- token: BasisTheory token ID
- provider: ‘basistheory’
- nonSensitiveMetadata: Card details like last4, brand, expiry, etc.
Security & Permissions:
- Requires org:admin role
- Requires storeId - validates that the authenticated account owns the store
- All operations are scoped to the authenticated user’s account
- If customerId is provided, it must belong to the authenticated account
- If customerData is provided, a new customer will be created in the authenticated account
Customer Handling:
- Provide either customerId (existing customer) OR customerData (new customer)
- Cannot provide both customerId and customerData
POST
/
api
/
public
/
v1
/
payment-instruments
/
create-from-token
curl --request POST \
--url https://api.tagada.io/api/public/v1/payment-instruments/create-from-token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tagadaToken": "eyJ0eXBlIjoiY2FyZCIsInRva2VuIjoiYnRfdG9rZW5fMTIzIiwicHJvdmlkZXIiOiJiYXNpc3RoZW9yeSIsIm5vblNlbnNpdGl2ZU1ldGFkYXRhIjp7Imxhc3Q0IjoiNDI0MiIsImJyYW5kIjoidmlzYSIsImV4cGlyeU1vbnRoIjoxMiwiZXhwaXJ5WWVhciI6MjAyNX19",
"storeId": "store_eaa20d619f6b",
"customerId": "cus_123"
}
'
{
"paymentInstrument": {
"id": "pi_123",
"type": "card",
"customerId": "cus_123",
"accountId": "acc_123",
"isActive": true,
"isDefault": false,
"tokenizer": "basistheory",
"createdAt": "2024-03-20T10:30:00Z",
"card": {
"last4": "4242",
"brand": "visa",
"expYear": 2025,
"expMonth": 12
}
},
"customer": {
"id": "cus_123",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"createdAt": "2024-03-20T10:30:00Z"
}
}
Authorizations
Enter your API key as: Bearer your-api-key
Body
application/json
Show child attributes
Show child attributes
The shopper behind this server-to-server call, as seen by YOUR server (IP, User-Agent). Kept on the customer's device record, so every later POST /payments/process on this customer carries it to the processor even when that call omits customer. Never your own server's address; an invalid IP is refused (400).
Show child attributes
Show child attributes
Response
Successful response