curl --request POST \
  --url https://app.tagadapay.com/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": "[email protected]",
    "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

payment-instruments

create-from-token

curl --request POST \
  --url https://app.tagadapay.com/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": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-03-20T10:30:00Z"
  }
}

Authorizations

Authorization

string

header

required

Enter your API key as: Bearer your-api-key

Body

application/json

tagadaToken

string

required

storeId

string

required

customerId

string

customerData

object

Show child attributes

customerData.email

string<email>

required

customerData.firstName

string

customerData.lastName

string

customerData.currency

string

default:USD

customerData.locale

string

default:en

customerData.billingAddress

any

customerData.shippingAddress

any

customerData.acceptsMarketing

boolean

default:false

Response

Successful response

List customer payment instruments Create 3DS session

⌘I

API documentation

API endpoints

Create payment instrument from TagadaToken

Authorizations

Body

Response