What is Cartão Protegido?

The Cartão Protegido is a platform that enables secure storage of credit and debit cards. We have a fully certified environment by the respected PCI Security Standards Council, which ensures that Braspag fully follows the strict requirements and standards determined by it.

The platform is compatible with Braspag’s Pagador gateway, facilitating the processing of credit and debit card transactions via token.

Main benefits

Use Cases

The purpose of the platform is to help establishments that have several use cases, including:

Architecture

Integration is made through services as Web Services. The model used is quite simple: Through the endpoint all requests related to this service will be sent. This URL will receive HTTP messages via POST, GET, or DEL methods. Each type of message must be sent to an address identified through “path”.

Endpoint Environment
https://cartaoprotegidoapisandbox.braspag.com.br/ Sandbox
https://cartaoprotegidoapi.braspag.com.br/ Production

How does it integrate?

Postman Collection

For those who want to try out the APIs directly via Postman, follow the link to download the collection:

Authentication Step

To consume API methods, you must get AccessToken in the OAuth 2.0 standard.

Environment Endpoint Authorization
SANDBOX https://authsandbox.braspag.com.br/oauth2/token Basic (Authorization)
The Authorization value must be obtained by concatenating the value of the “ClientID”, colon (“:”), and “ClientSecret”
E.g.: b4c14ad4-5184-4ca0-8d1a-d3a7276cead9:qYmZNOSo/5Tcjq7Nl2wTfw8wuC6Z8gqFAzc/utxYjfs=
and then encode the result in base 64.
This will generate an alphanumeric access code that will be used in the access token. For testing purposes, use the following data: ClientID
: ** b4c14ad4-5184-4ca0-8d1a-d3a7276cead9
ClientSecret:
qYmZNOSo/5Tcjq7Nl2wTfw8wuC6Z8gqFAzc/utxYjfs=**
PRODUCTION https://auth.braspag.com.br/oauth2/token Request the “ClientID” and “ClientSecret” data from the support team after completing sandbox development.

Request

--request POST "https://authsandbox.braspag.com.br/oauth2/token"
--header "Authorization: Basic _(Authorization)_"
--header "Content-Type: application/x-www-form-urlencoded"
--body "grant_type=client_credentials"
Parameters Description
Authorization Basic (Authorization)
Content-Type application/x-www-form-urlencoded
grant_type client_credentials

Response

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
curl
{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
Response Properties Description
access_token The requested access token. The application can use this token to authenticate with the protected resource  
token_type Indicates the value of the token type  
expires_in Expiration of the access token, in seconds
The token when expiring, it is necessary to get a new
 

Create Token Reference

The purpose of this method is to save a card and get the token reference (Token Reference) as a response.

Request

{
    "Alias":"5R2O4042YP",
    "Card": {
        "Number": "4551870000000183",
        "Holder": "Joao da Silva",
        "ExpirationDate": "12/2021",
        "SecurityCode": "123"
    }
}
curl
--request POST "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
{
    "Alias":"5R2O4042YP",
    "Card": {
        "Number": "4551870000000183",
        "Holder": "Joao da Silva",
        "ExpirationDate": "12/2021",
        "SecurityCode": "123"
    }
}
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox / Production)
Authorization Text - Yes ** Bearer ** _ (Authorization) _
(is the access token generated in the previous step)
Content-Type Text - Yes application / json
Alias Text 64 No Card Alias. The value of this information must be unique (cannot repeat).
Card.Number Number 16 Yes Shopper Card Number
Card.Holder Text 25 Yes Shopper’s Name Printed on Card
Card.ExpirationDate Text 7 Yes Expiration date printed on card in MM / YYYY format
Card.SecurityCode Number 4 Yes Security code printed on back of card

Response

{
    "Alias": "5R2O4042YP",
    "TokenReference": "c2e0d46e-6a78-409b-9ad4-75bcb3985762",
    "ExpirationDate": "2021-12-31",
    "Card": {
        "Number": "************0183",
        "ExpirationDate": "12/2021",
        "Holder": "Joao da Silva",
        "SecurityCode": "***"
    },
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762"
        },
        {
            "Method": "PUT",
            "Rel": "suspend",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762/suspend"
        }
    ]
}
curl
--request POST "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token"
--header "Content-Type: application/json"
--data-binary
{
    "Alias": "5R2O4042YP",
    "TokenReference": "c2e0d46e-6a78-409b-9ad4-75bcb3985762",
    "ExpirationDate": "2021-12-31",
    "Card": {
        "Number": "************0183",
        "ExpirationDate": "12/2021",
        "Holder": "Joao da Silva",
        "SecurityCode": "***"
    },
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762"
        },
        {
            "Method": "PUT",
            "Rel": "suspend",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/c2e0d46e-6a78-409b-9ad4-75bcb3985762/suspend"
        }
    ]
}
Properties Description Type Size Format
Alias Credit Card Alias Text 64 Any text that is unique to the establishment’s token base
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ExpirationDate Token Expiration Date, format MM/YYYY Text 7 MM/YYYY
Card.Number Número 16 Sim Masked card number
CreditCard.Holder Text 25 Yes Name of cardholder printed on card
Card.ExpirationDate Text 7 Yes Expiration date printed on card in MM/YYYY format
Card.SecurityCode Number 4 Yes Security code printed on back of masked card

Get Token Reference Information

The purpose of this method is to obtain information related to a token reference, such as Status, Masked Card, Expiration Date, and Card Holder Name.

Request

curl
--request GET "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox / Production)
Authorization Text - Yes Bearer _ (Authorization) _
(is the access token generated in the previous step)
Content-Type Text - Yes application/json
TokenReference GUID 36 Yes Token on Protected Card representing card data

Response

{
    "TokenReference": "1fdb4ef8-17f3-4f26-87e9-3a5f34bca8a0",
    "Status": "Active",
    "Provider": "Braspag",
    "Account": {
        "Number": "************0183",
        "ExpirationDate": "12/2021",
        "Holder": "Runscope Teste"
    }
}
curl
--request GET "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}"
--header "Content-Type: application/json"
--data-binary
{
    "TokenReference": "1fdb4ef8-17f3-4f26-87e9-3a5f34bca8a0",
    "Status": "Active",
    "Provider": "Braspag",
    "Account": {
        "Number": "************0183",
        "ExpirationDate": "12/2021",
        "Holder": "Runscope Teste"
    }
}
Properties Description Type Size Format        
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx        
Status Text 10 No Current Cartão Protegido token status   - Possible values: Active, Removed, Suspended Text
Provider Indicates the provider that stored the card. - Possible values: Braspag or Master Text        
Account.Number Masked Buyer Card Number Text 16 -        
Account.Holder Shopper’s Name printed on card, without accented characters Text 25 Example: Jose da Silva        
Account.ExpirationDate Expiration date printed on card in MM / YYYY format Text 7 Example: 12/2021        

Get Token Reference

The purpose of this method is to get the token reference from a previously entered alias.

Request

curl
--request GET "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Alias/_{Alias}_/TokenReference"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox/Production)
Authorization Text - Yes Bearer (Authorization)
(is the access token generated in the previous step)
Content-Type Text - Yes application/json
Alias Text 64 No Alias of credit card previously used in Create Token method

Response

{
    "TokenReference": "a36ffc37-e472-4d85-af2a-6f64c52bcccf"
}
curl
--request GET "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Alias/_{Alias}_/TokenReference"
--header "Content-Type: application/json"
--data-binary
{
    "TokenReference": "a36ffc37-e472-4d85-af2a-6f64c52bcccf"
}
Property Description Type Size Format
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Delete Token Reference

The purpose of this method is to remove the base token reference permanently. The Token Reference removed by this method does not allow it to be recovered in the future.

Request

{
     "RemovedBy":"Merchant",
     "Reason":"Other"
}
curl
--request DELETE "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
{
     "RemovedBy":"Merchant",
     "Reason":"Other"
}
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox/Production)
Authorization Text - Yes ** Bearer ** (Authorization)
(is the access token generated in the previous step)
Content-Type Text - Yes application/json
RemovedBy Text 10 Yes Who requested the removal. Possible values: ‘Merchant’ or ‘CardHolder’
Reason Text 10 Yes Reason for token removal. Possible values: ‘FraudSuspicion’ or ‘Other’

Response

{
    "TokenReference": "26eb7cb4-c2b4-4409-8d2e-810215c42eee",
    "Status": "Removed",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/26eb7cb4-c2b4-4409-8d2e-810215c42eee"
        }
    ]
}
curl
--request DELETE "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}"
--header "Content-Type: application/json"
--data-binary
{
    "TokenReference": "26eb7cb4-c2b4-4409-8d2e-810215c42eee",
    "Status": "Removed",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/26eb7cb4-c2b4-4409-8d2e-810215c42eee"
        }
    ]
}
Property Description Type Size Format
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Text 10 No Current Cartão Protegido token status

Suspend Token Reference

The purpose of this method is to suspend a token reference temporarily. Token Reference suspended by this method can be reactivated via the Unsuspend Token Reference method.

Request

{
     "RemovedBy":"Merchant",
     "Reason":"FraudSuspicion"
}
curl
--request PUT "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}/suspend"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
{
     "RemovedBy":"Merchant",
     "Reason":"FraudSuspicion"
}
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox/Production)
Authorization Text - Yes Bearer (Authorization)
(is the access token generated in the previous step)
Content-Type Text - Yes application/json
RemovedBy Text 10 Yes Who requested the removal. Possible values: ‘Merchant’ or ‘CardHolder’
Reason Text 10 Yes Reason for token removal. Possible values: ‘FraudSuspicion’ or ‘Other’

Response

{
    "TokenReference": "0a69a878-e50a-4252-bccc-24942a6225a9",
    "Status": "Suspended",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        }
    ]
}
curl
--request PUT "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}/suspend"
--header "Content-Type: application/json"
--data-binary
{
    "TokenReference": "0a69a878-e50a-4252-bccc-24942a6225a9",
    "Status": "Suspended",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        }
    ]
}
Property Description Type Size Format
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Text 10 No Current Cartão Protegido token status

Unsuspend Token Reference

The purpose of this method is to reactivate a token reference.

Request

curl
--request PUT "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}/unsuspend"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "Authorization: Bearer {access_token}"
--data-binary
Parameters Type Size Required Description
MerchantID GUID - Yes Cartão Protegido’s Merchant ID in their environment (Sandbox/Production)
Authorization Text - Yes Bearer (Authorization)
(is the access token generated in the previous step)
Content-Type Text - Yes application/json

Response

{
    "TokenReference": "0a69a878-e50a-4252-bccc-24942a6225a9",
    "Status": "Active",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "PUT",
            "Rel": "suspend",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9/suspend"
        }
    ]
}
curl
--request PUT "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/{TokenReference}/unsuspend"
--header "Content-Type: application/json"
--data-binary
{
    "TokenReference": "0a69a878-e50a-4252-bccc-24942a6225a9",
    "Status": "Active",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "DELETE",
            "Rel": "remove",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9"
        },
        {
            "Method": "PUT",
            "Rel": "suspend",
            "HRef": "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token/0a69a878-e50a-4252-bccc-24942a6225a9/suspend"
        }
    ]
}
Property Description Type Size Format  
TokenReference Token on Cartão Protegido representing card data GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  
Status Text 10 No Current Cartão Protegido token status  

Error codes

In case of error in the request, the error codes and their description will be informed, as the example.

Response

{
    "Errors": [
        {
            "Code": "CP903",
            "Message": "Token alias already exists"
        }
    ]
}
curl
--request PUT "https://cartaoprotegidoapisandbox.braspag.com.br/v1/Token"
--header "Content-Type: application/json"
--data-binary
{
    "Errors": [
        {
            "Code": "CP903",
            "Message": "Token alias already exists"
        }
    ]
}
Code Message Description
CP903 Token alias already exists Happens when Alias has been previously used.
CP990 ‘XXXXX’ must not be empty. Happens when any field is invalid.

Implementation Tips

Card Security Code

The security code is required for an authorization to be accepted by the card issuing bank. It is another security mechanism in the anti-fraud process, where it seeks to validate that the person who is using the card is in fact its owner. For this reason, PCI rules allow you to store the card number and validity, but never the security code, not even the PCI certified Braspag. The recommendation is that the CVV is always requested at the time of purchase.

One click payment

A tip to improve your conversion is to save the masked card number to show the customer which card they have enabled for the “1 click payment” on the site;