Paying with Credit Card
We currently offer two procedures to create a credit card transaction, in the first one the title is created in a single step, thus being conventionally One Step. The second option to create the transaction takes place in two steps, thus being called Two Steps. Both are detailed below:
1. Creating One Step transaction
important
For the One Step transaction to occur, it is normally necessary to update your SDK. All the files necessary for this are available in our github repository and in our documentation.
In the credit card transactions, a step prior to creation will be carried out where the card data is transmitted (via JavaScript, in the browser), in a secure way, off the card data and and returning a payment_token, and in the second step your backend sends the rest of the transaction information and thepayment_token obtained in the first step.
important
It's important to emphasize that it is not possible to pay by credit card without the payment_token of the transaction, therefore, it is essential to execute the procedures in item 1.1 of this document (obtaining the payment_token), and only after move on to item 1.2 (which is properly the card payment).
1.1. Obtaining the payment_token
Let's do the first step, which is obtaining the payment_token. To do so, you will need a JavaScript code specific to your Gerencianet account. To generate it, follow the steps:
- Log in your Gerencianet account and access
"Minha Conta"(top right corner) - Copy the
"Identificador de Conta"(see how) - Paste in the field below and click the button
Gerar
It's important to make sure that the card data is obtained via JavaScript, in the browser, in a secure way, and the return of the payment_token, which is the representation of the data tha was sent.
important
Remember that, after informing your account identifier, 2 (two) distinct JavaScript codes will be generated.
Copy and use the code referring to the environment that is going to be used, paying attention to the differences between the "Homologation" and "Production" environments.
For web applications, you must copy the script above, specific to your account, and use our Javascript library, as per the snippet below. If you have a mobile app, check out how to proceed by accessing our GitHub page to Android and/or iOS.
In addition, we explain that a Gerencianet account doesn't have a payment_token - it is different and created for each charge generated by credit card. It represents the payer's card data and is obtained by the getPaymentToken function. In addition, it should be noted that the payment_token can be used only once, therefore, it is not possible to use it to charge on a recurring basis.
a) Get the "payment_token" ( getPaymentToken ):
- Código
b) Getting information about installments ( getInstallments ):
- Código
c) Attributes related to sending card data:
$gn.ready ( callback )
| Parameter | Description | Type |
|---|---|---|
callback | Initialization function that makes it possible to call functions getPaymentToken and getInstallments. Callback parameter(s): object// Object that receives instances of other functions. | Function |
getPaymentToken ( card_data, callback )
| Parameter | Description | Type |
|---|---|---|
card_data | Object that contains card data. The properties of this object are: brand// Card brand number// Card numbercvv// Card security code expiration_month// Expiration month of the card in "MM" formatexpiration_year// Card expiry year in "YYYY" format | Object |
callback | Function that receives the response from Gerencianet. Callback parameter(s): error// If it wasn't possible to generate the payment_token, errors will be returned in this parameter. response// Receives the data representing the credit card: payment_token e card_mask | Function |
getInstallments ( total, brand, callback )
| Parameter | Description | Type |
|---|---|---|
total | Total billing amount, including shipping, in cents. For example: R$ 230,90 is equivalent to 23090. | Integer |
brand | Card brand that you want to obtain the amounts of installments. Possible values: visa// Visa brandmastercard// MasterCard brandamex// AmericanExpress brandelo// Elo brandhipercard//Hipercard brand | String |
callback | Function that receives the response from Gerencianet. Callback parameter(s): error// If payment data could not be obtained, errors will be returned in this parameter.response//Receives data related to the type of payment consulted. | Function |
1.2. Paying with card
Now that the payment_token has already been obtained through the Javascript code of the first step, let's proceed with the credit card payment.
In this step, your backend sends the rest of the transaction information and the payment_token obtained in the first step.
When paying for a transaction by credit card, the status changes from new to waiting. This means that the transaction is associated with a payment method and is waiting for payment confirmation.
Once the payment is confirmed, the transaction status will change from waiting to paid. But if for some reason the payment cannot be confirmed, the status will change to unpaid.
The example below shows how this can be done, using the SDK's available:
- PHP
- Python
- NodeJS
- .NET
- Java
- GO
- Ruby
- Delphi
a) Hierarchical structure of Schema attributes that can be used:
b) Attributes that can be used to create a transaction:
| Attribute | Description | Required | Type |
|---|---|---|---|
items | item being sold. The same transaction can have unlimited items. Items attributes: name*// Name of the item, product or service. Minimum of 1 character and maximum of 255 characters (String).value*// Value, in cents of real. Example: R$ 10,00 = 1000. Integeramount// Amount. Integer | Yes | Array |
shippings | Determines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values. Shippings attributes: name*// Shipping label Máximo de 255 caracteres. String.value*// Shipping value, in cents of real (1990 is equivalent to R$19,90). Integer | No | Array |
metadata | Define transaction-specific data Metadata attributes: custom_id// It allows associating a Gerencianet transaction with a specific ID of your system or application, allowing you to identify it, if you have, a specific ID and want to keep it. Maximum of 255 caracteres. String/null.notification_url// Address of your valid URL that will receive transaction status change notifications. Maximum of 255 caracteres. String/null. | No | Object |
Object Payment
| Attribute | Description | Required | Type |
|---|---|---|---|
credit_card | Object containing the necessary information for credit card payment, such as the number of installments and customer data. | Yes | Object Credit_Card |
Object Credit_Card
| Attribute | Description | Required | Type |
|---|---|---|---|
customer | Payer's personal data. Customer attributes: name* // Payer's name (String)cpf* // Customer CPF (no dots, commas or hyphens).(String)email* // Customer's valid email address. (String)phone_number* // Valid customer phone number, no special characters. (String)birth* // Customer's Date of Birth (valid date in YYYY-MM-DD format). (String)address // Delivery address. (Object) (more info)juridical_person // Legal entity data.(Object) (more info) | Yes | Object |
installments | Number of installments in which the payment must be divided. Minimum 1 and maximum 12. Integer. | No | Integer |
discount | Defines discount data about the billing. Discount attributes: type*// Discount type (String). Allowed values: currency: the discount will be entered in Real cents. percentage: the discount will be entered in percentagecnpj*//company's CNPJ. Size: 14 caracteres. String.value*// Discount value (Integer). If the discount type is currency , the value of this tag must be informed by the developer in cents of real (that is, 500 is equivalent to R$ 5.00). If the discount type is percentage, the value must be multiplied by 100 (that is 1500 is equivalent to 15%). Examples: 1) currency// must be informed in cents of real, that is, if the discount will be R$ 5.99, the developer must inform 599;2) percentage // must be informed in cents of real, that is, if the discount is 15%, the developer must inform 1500. | No | Object |
billing_address | Billing address (more info) billing_address attributes: street*// street name (Object)number*// number (String/Integer)neighborhood*// Neighborhood (String)zipcode*// zipcode (no dots or hyphen) (String)city*// City (String)complement// Complement (String/null)state*// state (2 caracteres) (Object) | No | Object |
payment_token | Unique payment token obtained in the first step of transaction generation. | Yes | String |
message | Allows you to include an "observation" in the billing, or in other words, a message to the customer. This message can be seen in the emails related to the billing, in the slip or carnet. Up to 4 lines containing 100 characters on each line. String. The operator \nis used to perform the line break. | No | String |
Fields with * represents required attributes
2. Creating a Credit Card Transaction in Two Steps
In this option, it is necessary that the body of the request has all the minimum attributes required to create the charge. Below are implementation examples using the available SDK's:
2.1. Create the transaction, informing the item/product/service, value, quantity, etc;
2.2. Associate with the payment method: card , informing the charge_id of the transaction created and the customer data;
2.3. Getting the payment_token (via JavaScript, unique per transaction);
2.4. Paying with card.
As it is a payment via card and involves sensitive data, such as credit card data, the procedures described in items 3.1 and 3.2, that is, obtaining the payment_token and paying by card, respectively, are necessary.
The rest of this page has the detailed procedures, but you need to install one of our libraries on your server to run the sample code. Make sure that the Gerencianet SDK has been installed.
2.1. Creating transaction
First, we need to generate the transaction (also called "charge"). It is at this moment that the name of the item/product/service, transaction value, quantity, among other possible information will be informed.
After creating it, the charge_id will be returned, which is the unique identifier of the transaction and will be used to associate the payment method.
As soon as this transaction is created, it receives the status new, which means that the charge has been generated and is awaiting definition of the payment method. This charge will only change its status when the integrator defines your payment method.
To generate a transaction, you must send a request POST to the route /v1/charge.
If you want, you can explore and learn more about this feature using our Playground.
The example below shows how this can be done, using the SDK's available:
- PHP
- Python
- NodeJS
- .NET
- Java
- GO
- Ruby
- Delphi
a) Hierarchical structure of Schema attributes that can be used:
b) Attributes that can be used to create a transaction:
| Attribute | Description | Required | Type |
|---|---|---|---|
items | item being sold. The same transaction can have unlimited items. Item attributes: name*// Name of the item, product or service. Minimum of 1 character and maximum of 255 characters (String).value*// Value, in Real cents. Ex: R$ 10,00 = 1000. Integeramount// amount Integer | Yes | Array |
shippings | Determines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values. Shippings attributes: name*// Shipping label. Maximum of 255 caracteres. String.value*// Shipping value, in Real cents (1990 is equivalent to R$19.90).Integer | No | Array |
metadata | Define transaction-specific data Metadata attributes: custom_id// It allows associating a Gerencianet transaction with a specific ID of your system or application, allowing you to identify it if you have a specific ID and want to keep it. Maximum of 255 caracteres. String/null.notification_url// Address of your valid URL that will receive transaction status change notifications. Maximum of 255 characters. String/null. | No | Object |
Field wih * represent required values
2.2. Associate with the card payment method
Once the transaction has been created, we will associate it with the payment method, which in this case will be a credit card. To do so, the charge_id obtained in the previous consumption in which the transaction was generated must be informed.
In the case of credit card transactions, it will be carried out in two steps, the first is the transmission (via JavaScript, in the browser), in a secure way, of the card data and returning a payment_token, and in the second step your backend sends the rest of the transaction information and the payment_token obtained in the first step.
IMPORTANT - ABOUT THE PAYMENT_TOKEN
It is important to emphasize that it is not possible to pay by credit card without obtaining the payment_token of the transaction, therefore, it is essential to carry out the procedures of item 2.1 of this document (obtaining the payment_token), and only then move on to item 2.2 (which is trully the card payment).
To associate the payment method, you must send a POST request to the /v1/charge/:id/pay route, where :id is the charge_id of the transaction in the case.
2.3. Obtaining the payment_token
Initially, we will be doing the first step, which is to obtain the payment_token. To do so, you will need a JavaScript code specific to your Gerencianet account. To generate it, follow the steps:
- Log in your Gerencianet account and access
Minha Conta(top right corner) - Copy your
"Identificador de Conta"(see how) - Paste in the field below and click the button
Generate
It is important to emphasize that it is obtained via JavaScript, in the browser, in a secure way, the card data and returns a payment_token, which is the representation of the sent data.
important
Remember that, after informing your account identifier, 2 (two) distinct JavaScript codes will be generated.
Copy and use the code referring to the desired environment, paying attention to the differences between the "Development" and "Production" environments.
For web applications, you must copy the script above, specific to your account, and use our Javascript library, as shown the snippet below. If you have a mobile app, check out how to proceed by accessing our GitHub page to Android or iOS.
In addition, we clarify that a Gerencianet account does not have a payment_token- it is different and created for each generated charge by credit card. It represents the payer's card data and is obtained by the getPaymentToken function. Besides that, it should be noted that the payment_token can be used only once, therefore, it is not possible to use it to a recurrently charge.
a) Getting a "payment_token" ( getPaymentToken ):
- Código
b) Getting information about installments ( getInstallments ):
- Código
c) Attributes related to sending card data:
$gn.ready ( callback )
| Parameter | Descrição | Tipo |
|---|---|---|
callback | Initialization function that makes it possible to call functions getPaymentToken e getInstallments. Parâmetro(s) de callback: object// Object that receives instances of other functions. | Function |
getPaymentToken ( card_data, callback )
| Parameter | Description | Type |
|---|---|---|
card_data | Object that contains card data. The properties of this object are: brand// card flag number// Card number without formattingcvv// card security code expiration_month// Card expiry month in format "MM"expiration_year// Card expiry year in format "YYYY" | Object |
callback | Function that receives the response from Gerencianet. Callback parameter(s): error// If it was not possible to generate the payment_token, errors will be returned in this parameter. response// Receives the data representing the credit card: payment_token and card_mask | Function |
getInstallments ( total, brand, callback )
| Parameter | Description | Type |
|---|---|---|
total | Total billing amount, including shipping, in cents. For example: R$ 230,90 equals to 23090. | Integer |
brand | Brand of the card that you want to obtain the amounts of installments. Possible values: visa// Brand Visamastercard// Brand MasterCardamex// Brand AmericanExpresselo// Brand Elohipercard// Brand Hipercard | String |
callback | Function that receives the response from Gerencianet. Callback parameter(s): error//If payment data could not be obtained, errors will be returned in this parameter.response// Receives data related to the type of payment consulted. | Function |
2.4. Paying with credit card
Now that the payment_token has already been obtained through the Javascript code of the first step, let's proceed with the credit card payment.
In this step, your backend sends the rest of the transaction information and the payment_token obtained in the first step.
When paying for a transaction by credit card, the status changes from new to waiting. This means that the transaction is associated with a payment method and is waiting for payment confirmation.
Once the payment is confirmed, the transaction will change status from waiting to paid.But, if for some reason it is not possible to confirm the payment, the status will change to unpaid.
The example below shows how this can be done, using the SDK's available:
- PHP
- Python
- NodeJS
- .NET
- Java
- GO
- Ruby
- Delphi
a) Hierarchical structure of Schema attributes that can be used in the requisition:
b) Attributes related to credit card payment:
Parâmetros da url
| Attribute | Description | Mandatory | Type |
|---|---|---|---|
id | transaction identifier (charge_id) | Yes | Object ID |
Objeto ID
| Attribute | Description | Mandatory | Type |
|---|---|---|---|
payment | Root tag | Yes | Object Payment |
Object Payment
| Attribute | Description | Mandatory | Type |
|---|---|---|---|
credit_card | Object containing the necessary information for payment via credit card, such as the number of installments and customer data. | Yes | Object Credit_Card |
Object Credit_Card
| Attribute | Description | Mandatory | Type |
|---|---|---|---|
customer | Payer's personal data. Attibutes of customer: name* // Name (String)cpf* // customer's CPF (no dots, commas or hyphens).(String)email* // Customer's valid email address. (String)phone_number* // Valid customer phone number, no special characters. (String)birth* // Customer's date of birth (valid date in format YYYY-MM-DD). (String)address // Delivery address. (Object) (more information)juridical_person // Legal person data. (Object) (more information) | Yes | Object |
installments | Number of installments into which the payment must be divided. Minimum 1 and maximum 12. Integer. | No | Integer |
discount | Defines discount data about the charge. Attributes of discount: type*// Discount type (String).Allowed values: currency: the discount will be reported in cents. percentage: the discount will be informed in percentage.cnpj*// Company CNPJ. Size: 14 characters. String.value*// Discount amount (Integer). If the discount type is currency ,the value of this tag must be informed by the integrator in cents (that is, 500 equals to R$ 5,00). If the discount type is percentage,the value must be multiplied by 100 (that is, 1500 equals to 15%). Exemples: 1) currency// must be informed in cents, that is, if the discount will be R$ 5,99,the integrator must inform 599;2) percentage // must be informed in cents, that is, if the discount is 15%, the integrator must inform 1500. | No | Object |
billing_address | Billing address (more info) Attributes of billing_address: street*// Street name (Object)number*// Number (String/Integer)neighborhood*// Neighborhood (String)zipcode*// CEP (without dots or hyphen) (String)city*// City (String)complement// Complement (String/null)state*// State (2 caracteres) (Object) | No | Object |
payment_token | Single payment token obtained in the first step of transaction generation. | Yes | String |
message | Allows you to include an "observation" in the billing, or in other words, a message to the customer. This message can be seen in the emails related to the billing, in the payment slip or carnet. Up to 4 lines containing 100 characters on each line. The operator \nis used to perform the line break. | No | String |
Fields with * represent mandatory values
The payment as a Legal Entity (PJ)
The customer associated with the transaction can be a Legal Entity. In this case, the Corporate Name and CNPJ of the paying company must be informed within the juridical_person attribute.
Check this link for details on how to generate a payment whose payment method is "credit card" for a customer who is a Legal Entity (PJ).
List of all possible status of a transaction
All transactions have their status. Therefore, it is important to know the possible statuses in the API to provide the proper handling in your system.
Check this link for details of all the possible status of transactions.
API transaction callbacks (notifications) to your system
Notifications allow you to be informed when a transaction has changed status. In this way, you will be able to identify when a charge is paid, for example.
Check this link for all the details on how to implement your notification URL.
3. Other endpoints
There are other endpoints and methods related to credit card payment that are available in the API and can be exploited by the integrator. Check out the complete list:
4. Videos: Creating transaction and paying via credit card
Thinking of offering new means of transmitting information, Gerencianet makes available the following videos in order to explain, in a clear and objective way, how to create a transaction via integration and associate it with the payment method by "credit card".
4.1. Creating transaction via Playground (test environment/sandbox)
4.2. Defining payment method by Credit Card (via Playground)
4.3. Creating a transaction by integration - Payment by Credit Card
Type
For access to other classes, on other subjects, access the Online Course on Integrations page.