Faça Sua Primeira Chamada à API do SpherePay

Este guia apresenta a sequência completa para sua primeira integração com o SpherePay: criar um cliente (customer), registrar uma conta bancária e carteira, e executar uma transferência de on-ramp. Ao final, você terá feito chamadas reais de API para todos os recursos centrais do modelo SpherePay. Todas as requisições vão para a URL base: https://api.spherepay.co/

Pré-requisitos

Você tem uma chave de API. Caso contrário, consulte Autenticação.
Você entende o modelo de integração. Caso contrário, leia Como funciona primeiro.

Criar um cliente

Crie um cliente pessoa física enviando uma requisição POST para /v2/customer. Inclua os dados de contato e as informações de identificação fiscal do cliente.

curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
      "line1": "233 South Wacker Drive",
      "line2": "Suite 4700",
      "city": "Chicago",
      "postalCode": "60606",
      "state": "IL",
      "country": "USA"
    },
    "personalInformation": {
      "taxIdentificationNumber": "123456789",
      "taxIdentificationNumberType": "ssn",
      "taxIdentificationNumberCountry": "USA"
    }
  }'

Uma resposta bem-sucedida retorna o objeto do cliente recém-criado com um id gerado pelo sistema e um array verificationProfiles mostrando o status do KYC como incomplete:

{
    "id": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "verificationProfiles": [
        {
            "name": "kyc_profile_a",
            "status": "incomplete",
            "criteria": {
                "complete": [],
                "pending": [],
                "required": [],
                "errors": []
            }
        }
    ],
    "createdAt": "2026-03-03T21:25:03.102Z",
    "updatedAt": "2026-03-03T21:25:03.102Z",
    "type": "individual"
}

O cliente deve completar a verificação KYC e atingir o status approved antes que você possa criar uma transferência em seu nome. O onboarding é um pré-requisito obrigatório para todas as transferências. Consulte o Fluxo de KYC Individual ou o Fluxo de KYB Empresarial para os próximos passos.

Registrar uma conta bancária

Assim que seu cliente tiver aprovação no KYC, registre a conta bancária (bank_account) que servirá como origem fiat para uma transferência de on-ramp. Envie uma requisição POST para /v2/bank-account com o ID do cliente e os detalhes da conta.

curl -X POST https://api.spherepay.co/v2/bank-account \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "bankName": "Chase",
    "accountName": "Jane Doe Checking",
    "accountOwner": {
      "accountHolderName": "Jane Doe",
      "address": {
        "line1": "233 South Wacker Drive",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60606",
        "country": "USA"
      }
    },
    "currency": "usd",
    "accountDetails": {
      "accountNumber": "123456789",
      "routingNumber": "021000021",
      "accountType": "checking"
    },
    "networks": ["ach"]
  }'

Uma resposta bem-sucedida retorna o objeto da conta bancária com um id gerado pelo sistema:

{
    "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "bankName": "Chase",
    "accountName": "Jane Doe Checking",
    "currency": "usd",
    "networks": ["ach"],
    "createdAt": "2026-03-03T21:30:00.000Z",
    "updatedAt": "2026-03-03T21:30:00.000Z"
}

Registrar uma carteira

Registre a carteira (wallet) cripto que servirá como destino para a transferência de on-ramp. Envie uma requisição POST para /v2/wallet com o ID do cliente e os detalhes da carteira.

curl -X POST https://api.spherepay.co/v2/wallet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc"
  }'

Uma resposta bem-sucedida retorna o objeto da carteira com um id gerado pelo sistema:

{
    "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc",
    "status": "active",
    "createdAt": "2026-03-03T21:35:00.000Z",
    "updatedAt": "2026-03-03T21:35:00.000Z"
}

Criar uma transferência de on-ramp

Com um cliente verificado, uma conta bancária e uma carteira registradas, você já pode criar uma transferência de on-ramp. Especifique a conta bancária como source e a carteira como destination.

curl -X POST https://api.spherepay.co/v2/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "customer": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "source": {
      "type": "bank_account",
      "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
      "currency": "usd",
      "network": "ach"
    },
    "destination": {
      "type": "wallet",
      "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "currency": "usdc",
      "network": "ethereum"
    }
  }'

Uma resposta bem-sucedida retorna o objeto da transferência. O status inicial será pendingFunding enquanto o SpherePay aguarda os fundos:

{
    "id": "payout_9z8y7x6w5v4u3t2s1r0q",
    "type": "on_ramp",
    "status": "pendingFunding",
    "customer": "customer_4fbb292cc6e447da8858e054d1937e7e"
}

Acompanhar o status da transferência

Consulte o status da transferência enviando uma requisição GET para /v2/transfer/{id} usando o id retornado na etapa anterior.

curl https://api.spherepay.co/v2/transfer/payout_9z8y7x6w5v4u3t2s1r0q \
  -H "Authorization: Bearer YOUR_API_KEY"

A resposta retorna o objeto da transferência com um campo status atualizado. Uma transferência avança por pendingFunding → fundsReceived → processing → succeeded (ou failed se ocorrer um erro). Consulte Ciclo de Vida da Transferência para todos os status possíveis e seus significados.

​Pré-requisitos

Pré-requisitos