Tokenização de Cartão Por Arranjo

A tokenização de cartão por arranjo permite que um comprador utilize seu cadastro e seus cartões em diferentes estabelecimentos de uma mesma plataforma, como um marketplace ou e-commerce com múltiplos vendedores.

Por exemplo, em uma plataforma de delivery, o comprador cadastra seu cartão uma única vez e pode utilizá-lo para comprar em diferentes restaurantes, sem precisar cadastrar o cartão novamente para cada estabelecimento.

Essa funcionalidade atende plataformas que possuem múltiplos estabelecimentos e desejam compartilhar o cadastro do comprador e seus cartões entre as subcontas de um mesmo tenant.

Nesse artigo você irá aprender sobre:

• O funcionamento da tokenização de cartão por arranjo.
• As regras de utilização dos clientes e cartões entre as contas.
• O cadastro do cliente e do cartão na conta master.
• A utilização desses cadastros nas operações das subcontas.

Como funciona

Na estrutura da Celcoin, o tenant representa a plataforma e possui uma conta master vinculada. As subcontas pertencem ao mesmo tenant e representam os estabelecimentos que realizam as vendas.

Para permitir que o comprador utilize seus cartões nos diferentes estabelecimentos da plataforma, o integrador deve cadastrar tanto o cliente quanto o cartão na conta master. As cobranças são realizadas na subconta do estabelecimento, utilizando os cadastros da master.

Se o cliente e o cartão forem cadastrados diretamente em uma subconta, esses registros poderão ser utilizados apenas nas operações dessa mesma subconta.

Exemplos de uso

Considere um marketplace com dois estabelecimentos: loja A e loja B. As duas lojas são subcontas do mesmo tenant.

Limitações e exceções

• O compartilhamento se aplica aos clientes e cartões cadastrados na conta master do mesmo tenant das subcontas que realizarão as operações.
• Cadastrar apenas o cliente na master não é suficiente: o cartão também deve ser cadastrado na master e vinculado a esse cliente.
• Clientes e cartões cadastrados diretamente em uma subconta ficam restritos àquela subconta.
  

Endpoints de referência

Para implementar esse fluxo, utilize os endpoints de Clientes e Cartões para cadastrar o comprador e seu cartão na conta master informando obrigatóriamente o myId.

Para utilizar esses cadastros nas transações das subcontas, utilize os endpoints de Cobrança avulsa, Assinaturas e Contratos informando o myId do cartão e cliente cadastrado na master, conforme a operação que deseja realizar.

Cadastrar o cliente na conta master

Para cadastrar o comprador, utilize o endpoint de Clientes, direcionando a requisição para a conta master.

No exemplo abaixo, o campo myId identifica o cliente na sua integração e será utilizado para referenciá-lo na criação da cobrança.

Modelo de requisição:

curl --request POST \
     --url 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/customers?account=123456' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "myId": "cliente-0001",
    "name": "Maria da Silva",
    "document": "39379495005",
    "emails": ["[email protected]"],
    "phones": ["31999998888"]
}'

Consulte a referência do endpoint para verificar os campos obrigatórios e os demais parâmetros disponíveis.

Cadastrar o cartão na conta master

Após cadastrar o cliente, utilize o endpoint de Cartões para cadastrar o cartão na mesma conta master, vinculando-o ao comprador.

No exemplo abaixo, cliente-0001 identifica o cliente cadastrado no passo anterior. O cartão recebe o identificador cartao-0001 no campo myId.

Modelo de requisição:

curl --request POST \
     --url 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/cards/cartao-0001/myId?account=123456' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "cryptData": "12313213123"
}
'

Consulte a referência do endpoint para verificar os campos obrigatórios e os demais parâmetros disponíveis.

Exemplo: Criar uma cobrança na subconta

Com o cliente e o cartão cadastrados na conta master, utilize o endpoint de Cobrança avulsa para criar a cobrança na subconta do estabelecimento responsável pela venda.

No exemplo abaixo, a requisição utiliza o token da subconta e referencia o cliente e o cartão pelos identificadores definidos nos passos anteriores.

Modelo de requisição:

curl --request POST \
  --url 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges?account=798998' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '
{
  "value": 500,
  "payday": "2026-11-10",
  "mainPaymentMethodId": "creditcard",
  "Customer": {
    "myId": "cliente-0001"
  },
  "PaymentMethodCreditCard": {
    "Card": {
      "myId": "cartao-0001"
    },
    "cardOperatorId": "galaxPay"
  }
}
'

Para referenciar os cadastros existentes no modelo apresentado, informe apenas o myId dentro dos objetos Customer e Card, conforme o exemplo.

Exemplo de retorno:

{
    "type": true,
    "Charge": {
        "galaxPayId": 1991,
        "status": "closed",
        "Customer": {
            "myId": "cliente-0001",
            "galaxPayId": 1355,
            "name": "Maria da Silva"
        },
        "PaymentMethodCreditCard": {
            "Card": {
                "myId": "cartao-0001",
                "galaxPayId": 1638
            }
        }
    }
}

Importante:

Em cada operação, utilize a subconta do estabelecimento e referencie os cadastros da conta master nos campos previstos pelo respectivo endpoint.

Para uma nova compra em outro estabelecimento da mesma plataforma, utilize a subconta desse estabelecimento e os mesmos cadastros da master. Não é necessário que o integrador cadastre novamente o comprador e o cartão em cada subconta.