Add Payment Method

Tokenize a new card and attach it to a customer.

URL

POST /api/c2a/customer/payment/methods/add

Request Parameters

Body: PaymentMethodAddRequest.

Name	Type	Description
customerUrn	string	Required. Target customer.
paymentMethod	object (PaymentMethodDto)	Required. Channel + card payload. See Submit Checkout for the full DTO.

Request Example

{
  "customerUrn": "cu.00.482",
  "paymentMethod": {
    "paymentChannel": "CreditCard",
    "creditCard": {
      "cardHolderName": "Jane Doe",
      "cardNumber": "4111111111111111",
      "expireMonth": "12",
      "expireYear": "2029",
      "cvc": "123",
      "cardAlias": "Personal Visa"
    }
  }
}

Response Parameters

PaymentMethodAddResponse wraps AzottePaymentMethod.

Name	Type	Description
result.paymentMethodUrn	string	URN to reference the stored card.
result.customerUrn	string	Owning customer.
result.paymentChannel	string	CreditCard / PayPal / etc.
result.maskedCardNumber	string	e.g. 411111******1111.
result.cardType	string	VISA, MASTERCARD, etc.
result.expireMonth	string	MM.
result.expireYear	string	YYYY.
result.cardAlias	string	Optional user-facing label.
result.state	string	Active on success.
result.storedAt	string (date-time)	UTC timestamp.
status	object (AzotteStatus)	Operation status envelope.

Sample Response

{
  "result": {
    "paymentMethodUrn": "pm.00.482.7",
    "customerUrn": "cu.00.482",
    "paymentChannel": "CreditCard",
    "maskedCardNumber": "411111******1111",
    "cardType": "VISA",
    "expireMonth": "12",
    "expireYear": "2029",
    "cardAlias": "Personal Visa",
    "state": "Active",
    "storedAt": "2026-05-25T10:15:00Z"
  },
  "status": { "messageCode": "SUCCESS" }
}

PSP rejected

{
  "result": null,
  "status": { "messageCode": "CARD_DECLINED" }
}

Behaviour

• Raw PAN/CVC are sent over TLS to the PSP adapter; nothing sensitive is logged.
• On PSP failure, the response carries a non-success AzotteStatus (e.g. CARD_DECLINED, INVALID_CARD).
• Re-adding the same card creates a new record + new URN; Azotte does not deduplicate.

Sample Codes

cURL

curl --location 'https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add' \
  --header 'Content-Type: application/json' \
  --header 'x-tn: e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f' \
  --header 'x-api-key: sk_dev_acme_sample_123456789' \
  --data '{
    "customerUrn": "cu.00.482",
    "paymentMethod": {
      "paymentChannel": "CreditCard",
      "creditCard": {
        "cardHolderName": "Jane Doe",
        "cardNumber": "4111111111111111",
        "expireMonth": "12",
        "expireYear": "2029",
        "cvc": "123",
        "cardAlias": "Personal Visa"
      }
    }
  }'

JavaScript

const payload = {
  customerUrn: 'cu.00.482',
  paymentMethod: {
    paymentChannel: 'CreditCard',
    creditCard: {
      cardHolderName: 'Jane Doe',
      cardNumber: '4111111111111111',
      expireMonth: '12',
      expireYear: '2029',
      cvc: '123',
      cardAlias: 'Personal Visa'
    }
  }
};

const res = await fetch('https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tn': 'e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
    'x-api-key': 'sk_dev_acme_sample_123456789'
  },
  body: JSON.stringify(payload)
});
console.log(await res.json());

Node.js

import { request } from 'undici';

const payload = {
  customerUrn: 'cu.00.482',
  paymentMethod: {
    paymentChannel: 'CreditCard',
    creditCard: {
      cardHolderName: 'Jane Doe',
      cardNumber: '4111111111111111',
      expireMonth: '12',
      expireYear: '2029',
      cvc: '123',
      cardAlias: 'Personal Visa'
    }
  }
};

const { body } = await request(
  'https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-tn': 'e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
      'x-api-key': 'sk_dev_acme_sample_123456789'
    },
    body: JSON.stringify(payload)
  }
);
console.log(await body.json());

Python

import requests

payload = {
    "customerUrn": "cu.00.482",
    "paymentMethod": {
        "paymentChannel": "CreditCard",
        "creditCard": {
            "cardHolderName": "Jane Doe",
            "cardNumber": "4111111111111111",
            "expireMonth": "12",
            "expireYear": "2029",
            "cvc": "123",
            "cardAlias": "Personal Visa",
        },
    },
}

res = requests.post(
    "https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add",
    headers={
        "Content-Type": "application/json",
        "x-tn": "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f",
        "x-api-key": "sk_dev_acme_sample_123456789",
    },
    json=payload,
)
print(res.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String json = """
{
  "customerUrn": "cu.00.482",
  "paymentMethod": {
    "paymentChannel": "CreditCard",
    "creditCard": {
      "cardHolderName": "Jane Doe",
      "cardNumber": "4111111111111111",
      "expireMonth": "12",
      "expireYear": "2029",
      "cvc": "123",
      "cardAlias": "Personal Visa"
    }
  }
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add"))
    .header("Content-Type", "application/json")
    .header("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f")
    .header("x-api-key", "sk_dev_acme_sample_123456789")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

C#

using System.Net.Http.Json;

var payload = new {
    customerUrn = "cu.00.482",
    paymentMethod = new {
        paymentChannel = "CreditCard",
        creditCard = new {
            cardHolderName = "Jane Doe",
            cardNumber     = "4111111111111111",
            expireMonth    = "12",
            expireYear     = "2029",
            cvc            = "123",
            cardAlias      = "Personal Visa"
        }
    }
};

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f");
http.DefaultRequestHeaders.Add("x-api-key", "sk_dev_acme_sample_123456789");

var res = await http.PostAsJsonAsync(
    "https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add",
    payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

PHP

<?php
$payload = [
    'customerUrn'   => 'cu.00.482',
    'paymentMethod' => [
        'paymentChannel' => 'CreditCard',
        'creditCard'     => [
            'cardHolderName' => 'Jane Doe',
            'cardNumber'     => '4111111111111111',
            'expireMonth'    => '12',
            'expireYear'     => '2029',
            'cvc'            => '123',
            'cardAlias'      => 'Personal Visa',
        ],
    ],
];

$ch = curl_init('https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-tn: e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
        'x-api-key: sk_dev_acme_sample_123456789',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
echo curl_exec($ch);
curl_close($ch);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload := map[string]any{
        "customerUrn": "cu.00.482",
        "paymentMethod": map[string]any{
            "paymentChannel": "CreditCard",
            "creditCard": map[string]string{
                "cardHolderName": "Jane Doe",
                "cardNumber":     "4111111111111111",
                "expireMonth":    "12",
                "expireYear":     "2029",
                "cvc":            "123",
                "cardAlias":      "Personal Visa",
            },
        },
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST",
        "https://acme.sandbox.azotte.com/api/v1/c2a/customer/payment/methods/add",
        bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f")
    req.Header.Set("x-api-key", "sk_dev_acme_sample_123456789")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}