Chave de referência

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", 
 "card_number": "4556366941062122", 
 "card_cvv": "111", 
 "card_holder_name": "Aardvark da Silva", 
 "card_expiration_date": "1220", 
 "customer":{ 
   "email":"[email protected]", 
   "name":"Aardvark da Silva", 
   "document_number":"18152564000105", 
   "address":{ 
     "zipcode":"04571020", 
     "neighborhood":"Cidade Monções", 
     "street":"R. Dr. Geraldo Campos Moreira", 
     "street_number":"240" 
   }, 
   "phone": { 
     "number":"987654321", 
     "ddd":"11" 
   } 
 }, 
 "installments": 1, 
 "payment_method":"credit_card", 
 "amount": 1000, 
 "reference_key": "87a5742741f44cacbce14" 
} 
 
 

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

GET https://api.pagar.me/1/transactions?reference_key=87a5742741f44cacbce14 
{ 
"object": "transaction", 
"status": "paid", 
"refuse_reason": null, 
"status_reason": "acquirer", 
"acquirer_response_code": "0000", 
"acquirer_name": "pagarme", 
"acquirer_id": "596fd47b5415564c4d031ed8", 
"authorization_code": "817909", 
"soft_descriptor": null, 
"tid": 1780646, 
"nsu": 1780646, 
"date_created": "2017-08-01T18:40:40.937Z", 
"date_updated": "2017-08-01T18:40:41.600Z", 
"amount": 1000, 
"authorized_amount": 1000, 
"paid_amount": 1000, 
"refunded_amount": 0, 
"installments": 1, 
"id": 1780646, 
"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": "10.2.14.249", 
"subscription_id": null, 
"phone": { 
"object": "phone", 
"ddi": "55", 
"ddd": "11", 
"number": "987654321", 
"id": 138886 
}, 
"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": "Brasil", 
"id": 141940 
}, 
"customer": { 
"object": "customer", 
"id": 225536, 
"external_id": null, 
"type": null, 
"country": null, 
"document_number": "18152564000105", 
"document_type": "cnpj", 
"name": "Aardvark da Silva", 
"email": "[email protected]", 
"phones": null, 
"born_at": null, 
"birthday": null, 
"gender": null, 
"date_created": "2017-08-01T18:40:40.842Z", 
"documents": [] 
}, 
"billing": null, 
"shipping": null, 
"items": [], 
"card": { 
"object": "card", 
"id": "card_cj5txijfd002qhg6dzl1t6qkf", 
"date_created": "2017-08-01T18:40:40.922Z", 
"date_updated": "2017-08-01T18:40:41.677Z", 
"brand": "visa", 
"holder_name": "Aardvark da Silva", 
"first_digits": "455636", 
"last_digits": "2122", 
"country": "ARGENTINA", 
"fingerprint": "c84d30fd3c01dcd281aa765ad0e5c56582a6dd29", 
"valid": true, 
"expiration_date": "1220" 
}, 
"split_rules": null, 
"metadata": {}, 
"antifraud_metadata": {}, 
"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" 
}