Guides
GuidesSuporteAPI Reference

Chave de referência

Suggest Edits

O refence_key é um identificador provido pelo cliente para ser atrelado à uma transação. Use esse recurso, por exemplo, quando você não quiser (ou o seu sistema não suportar) o armazenamento de uma transaction_id para realizar transações.

❗️

Importante!

Esse dado deve ser único. Ou seja, não é possível criar mais de uma transação com a mesma chave de referência.

📘

Formato

Recomendamos a utilização de um dado com pelo menos 20 caracteres. Por exemplo: 87a5742741f44cacbce14

Documentação

campo: reference_key
tipo: string

Criando uma transação atrelada à uma Chave referência

POST /transactions
{
  "api_key": "SUA_API_KEY",
  "reference_key": "87a5742741f44cacbce14",
  "card_number": "4556366941062122",
  "card_cvv": "111",
  "card_holder_name": "Aardvark da Silva",
  "card_expiration_date": "1220",
  "installments": 1,
  "amount": 1000,
  "customer": {
    "external_id": "123",
    "type": "individual",
    "country": "br",
    "email": "[email protected]",
    "name": "Aardvark da Silva",
    "documents": [
      {
        "type": "cpf",
        "number": "00000000000"
      }
    ],
    "phone_numbers": [
      "+5511987654321"
    ]
  },
  "billing": {
    "name": "Trinity Moss",
    "address": {
      "country": "br",
      "state": "sp",
      "city": "São Paulo",
      "neighborhood": "Cidade Monções",
      "street": "R. Dr. Geraldo Campos Moreira",
      "street_number": "240",
      "zipcode": "04571020"
    }
  },
  "items": [
    {
      "id": "r123",
      "title": "Red pill",
      "unit_price": 10000,
      "quantity": 1,
      "tangible": true
    }
  ]
}

Recuperando uma transação através de uma Chave de referência 

GET /transactions?api_key=SUA_API_KEY&reference_key=87a5742741f44cacbce14
[
  {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "59ac5b4435075901002ba8fe",
    "authorization_code": "921316",
    "soft_descriptor": null,
    "tid": 1,
    "nsu": 1,
    "date_created": "2017-09-03T20:03:12.936Z",
    "date_updated": "2017-09-03T20:03:15.244Z",
    "amount": 1000,
    "authorized_amount": 1000,
    "paid_amount": 1000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1,
    "cost": 50,
    "card_holder_name": "Aardvark da Silva",
    "card_last_digits": "2122",
    "card_first_digits": "455636",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": null,
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
      "object": "customer",
      "id": 1,
      "external_id": "123",
      "type": "individual",
      "country": "br",
      "document_number": null,
      "document_type": "cpf",
      "name": "Aardvark da Silva",
      "email": "[email protected]",
      "phone_numbers": [
        "+5511987654321"
      ],
      "born_at": null,
      "birthday": null,
      "gender": null,
      "date_created": "2017-09-03T20:03:12.375Z",
      "documents": [
        {
          "object": "document",
          "id": "doc_cj755zs65000201qs5jkemyzm",
          "type": "cpf",
          "number": "00000000000"
        }
      ]
    },
    "billing": {
      "address": {
        "object": "address",
        "street": "R. Dr. Geraldo Campos Moreira",
        "complementary": null,
        "street_number": "240",
        "neighborhood": "Cidade Monções",
        "city": "São Paulo",
        "state": "sp",
        "zipcode": "04571020",
        "country": "br",
        "id": 1
      },
      "object": "billing",
      "id": 1,
      "name": "Trinity Moss"
    },
    "shipping": null,
    "items": [
      {
        "object": "item",
        "id": "r123",
        "title": "Red pill",
        "unit_price": 10000,
        "quantity": 1,
        "category": null,
        "tangible": true,
        "venue": null,
        "date": null
      }
    ],
    "card": {
      "object": "card",
      "id": "card_cj755zsek000301qsc91mfkw7",
      "date_created": "2017-09-03T20:03:12.909Z",
      "date_updated": "2017-09-03T20:03:15.379Z",
      "brand": "visa",
      "holder_name": "Aardvark da Silva",
      "first_digits": "455636",
      "last_digits": "2122",
      "country": null,
      "fingerprint": "IxJ5JRQV5pzs",
      "valid": true,
      "expiration_date": "1220"
    },
    "reference_key": "87a5742741f44cacbce14"
  }
]

Erro ao criar duas transações com a mesma Chave de referência

Se você tentar criar duas transações com a mesma Chave de referência, o seguinte erro é retornado:

{
  "errors": [
    {
      "type": "invalid_parameter",
      "parameter_name": "reference_key",
      "message": "Reference key must be unique"
    }
  ],
  "url": "/transactions",
  "method": "post"
}

Updated over 5 years ago