Create a Customer

Create a customer record to store billing identity, metadata, and future payment context.

Last updated

Author: Marco Silva

Authentication

Send your secret AtomicPay API key in the Authorization header. Never expose secret keys in client-side code.

Parameters

name

Customer full name or business name. This field is recommended when you want clearer support workflows and internal search.

email

Customer email used for receipts, account lookups, and operational follow-up.

metadata

Arbitrary key-value pairs for your own system identifiers such as CRM account id, sales region, or merchant segment.

Operational notes

Use metadata for system mapping, but avoid sensitive values such as full card data, passwords, or private health information.

POST/v1/customers

Base URL: https://api.atomicpay.com.br

Creates a customer and returns the full customer object when the payload is valid.

Request examples

curl

curl https://api.atomicpay.com.br/v1/customers \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jenny Rosen",
    "email": "jennyrosen@example.com",
    "metadata": {
      "crm_id": "crm_2048",
      "region": "br"
    }
  }'

customers.js

const response = await fetch('https://api.atomicpay.com.br/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ATOMICPAY_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jenny Rosen',
    email: 'jennyrosen@example.com',
    metadata: {
      crm_id: 'crm_2048',
      region: 'br',
    },
  }),
});

const customer = await response.json();

customers.php

$payload = [
  'name' => 'Jenny Rosen',
  'email' => 'jennyrosen@example.com',
  'metadata' => [
    'crm_id' => 'crm_2048',
    'region' => 'br',
  ],
];

$ch = curl_init('https://api.atomicpay.com.br/v1/customers');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $_ENV['ATOMICPAY_SECRET_KEY'],
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
]);

$customer = json_decode(curl_exec($ch), true);

customers.py

import os
import requests

response = requests.post(
    'https://api.atomicpay.com.br/v1/customers',
    headers={
        'Authorization': f"Bearer {os.environ['ATOMICPAY_SECRET_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Jenny Rosen',
        'email': 'jennyrosen@example.com',
        'metadata': {
            'crm_id': 'crm_2048',
            'region': 'br',
        },
    },
)

customer = response.json()

Response

response.json

{
  "id": "cus_Q8m1K2r4N6",
  "object": "customer",
  "name": "Jenny Rosen",
  "email": "jennyrosen@example.com",
  "metadata": {
    "crm_id": "crm_2048",
    "region": "br"
  },
  "created_at": "2026-04-06T11:45:00Z"
}

Related docs

Keep the momentum going

Documentation

Quickstart

Create your workspace, connect a provider, and publish your first payment flow.

April 3, 2026

Documentation

Connect a Payment Provider

Map credentials, callback URLs, and webhook signing secrets the safe way.

April 3, 2026