Home - POPRecarga/PartnerAPI GitHub Wiki

#Quick Links

• HOW TO USE
  • 1.Authentication
    • 1.1.Create Application
    • 1.2.Obtain an acess token
    • 1.3.Make an API call
  • 2.One-Time Payment
    • 2.1.Make your first payment
      • 2.1.1.Create Payment
      • 2.1.2.Payment Approval
      • 2.1.3.Cancel Payment
      • 2.1.4.Execute Payment
  • 3.Recurring Payments
    • 3.1.Getting a RecurringToken
    • 3.2.Payment using a RecurringToken
    • 3.3.Canceling a RecurringToken
  • 4.Chargebacks

• API RESOURCE REFERENCE
  • 1.Authentications
  • 2.Payment
  • 3.Recurring
  • 4.Chargeback
• Contact

#HOW TO USE

If you need a new payment method for your website, InDPV offers you the possibility to add POP recarga as online payment for those that don't have a bank account or credit card. They can purchase credits through sale points and use this credits in your website.

##1.Authentication

There are three simple steps in order to make your first REST API call.

###1.1.Create Application Request your ''client_id'' and ''client_secret'' from InPDV team([email protected]), or use the Sandbox Example Store in order to test our API calls.

###1.2.Obtain an access token Before your application can access InPDV private data using the API, it must obtain an access token that grants access to our API. To get an access token, use HTTP Basic Authentication in a /token call with the client id and secret and include a preset grant_type set to client_credentials in the request body. InPDV Authorization Server will send to your application an access token. The specific kind of access token that InPDV provides is called a “Bearer Token”.

The following is a POST request example to obtain access token:

POST /token HTTP/1.1
Host: api.sandbox.inpdv.com.br
content-type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 71

grant_type=client_credentials&client_id=3&client_secret=3333

The body of the request is all on one line. However, line feeds have been added to make the examples easier to read.

POST /token HTTP/1.1
Host: api.sandbox.inpdv.com.br 
content-type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 71

grant_type=client_credentials
&client_id=3
&client_secret=3333

The following is the sample response:

HTTP/1.1 200 OK
 
{
    "access_token":"BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…",
    "token_type":"bearer",
    "expires_in":3599
}

###1.3.Make an API call

Once you have your access token, you’re ready to start making your calls. Here’s a simple call to test InPDV API using just a few informations.

GET /users/me HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

The following is the sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "identifier":"MyUserName",
    "links":[]
}

InPDV-issued access tokens can be used to access all the REST API endpoints and have a finite lifetime. You must write code to detect when an access token expires. You can either do this by keeping track of the ‘expires_in’ value (returned as a value in seconds) in the token request, or handle the error response (401 Unauthorized) from the API endpoint when an expired token is used.

##2.One-Time Payment

The one-time payment involve three steps:

I.Pass payment information to create a payment: First collect payment details from the user and pass them to InPDV. We will create a pending transaction that needs user approval.

II.Payment approval: The user must approve the payment before you can execute and complete the sale. In order to do so, the user must give you an OTP.

III.Execute the payment: When the user approves the payment you can then, execute and complete it.

For all forms of payments using InPDV, the user must activate his account previously. If the user is not already active, he will finish the order upon completing his registration.

###2.1.Make your first payment

There are three simple steps to make your first payment using API Integration – SMS Token call.

####2.1.1.CREATE PAYMENT

To create a payment transaction you must to make a POST request in /payments resource.

The following is a POST request example to create a payment transaction.

POST /payments HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…
Content-Length: 190

{
    "brandId": 1,
    "identifier": "+5511XXXXXXXXX",
    "transaction": {
        "amount": 1.99,
        "currencyCode": "BRL",
        "description": "Product X",
        "referralCode": "a48s4d87g8a9d5v8h4k4az48f4"  
    }
}

Obs:The parameters “brandId”, “currencyCode” and "referralCode" are optional.

Obs2:The parameter “identifier” is a user phone number in E.164 format. e.g., +5511999999999

Obs3: InPDV API create its own transactionIds, if you want to keep track of your application generated ids use the parameter "referralCode"

The following is the sample response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
 
{
   "id":"5578a3ae-ee7f-4ed8-9e56-529da9f263d8",
   "links":[
   {
       "href":"https://api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8",
       "rel":"Self",
       "method":"Get"
   },
   {
       "href":"https://api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/token/{token-value}",
       "rel":"Approval",
       "method":"Put"
   },
   {
       "href":" https://api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/cancel",
       "rel":"Cancel",
       "method":"Put"
   }]
}

Obs: The response of create payment operation has all links that you need to get approve or cancel the specified >transaction.

####2.1.2.PAYMENT APPROVAL

To approve a payment transaction you must make a PUT request in /payments/{transactionId}/token/{token} resource, where {transactionId} is the identifier of a previously created transaction and {token} is alphanumeric value sent to the user.

The following is a PUT request example to approve a payment:

PUT /payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/token/{token} HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

The following is the sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "id":"0cf4e997-2c5d-4bf3-8238-1c4915c5cada",
    "links":[
    {
        "href":"https://api.sandbox.inpdv.com.br/payments/0cf4e997-2c5d-4bf3-8238-1c4915c5cada",
        "rel":"Self",
        "method":"Get"
    },
    {
        "href":"https://api.sandbox.inpdv.com.br/payments/0cf4e997-2c5d-4bf3-8238-1c4915c5cada/execute",
        "rel":"Execute",
        "method":"Put"
    },
    {
        "href":"https://api.sandbox.inpdv.com.br/payments/0cf4e997-2c5d-4bf3-8238-1c4915c5cada/cancel",
        "rel":"Cancel",
        "method":"Put"
    }]
}

Obs: The response of payment approval has all links that you need to execute or get the specified transaction.

####2.1.3.CANCEL PAYMENT To cancel a payment you must make a PUT request in /payments/{transactionId}/cancel resource, where {transactionId} is the identifier of a previously created or approved payment transaction.

The following is a PUT request example to cancel a payment:

PUT /payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/cancel HTTP/1.1
Host: sandbox.api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

Obs: The payment will be canceled should it not have been previously executed. You can cancel payment transactions already created or approved.

Obs2: All transactions pending approval or pending execution are automatically canceled after an interval.

The following is the sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "id":"0cf4e997-2c5d-4bf3-8238-1c4915c5cada",
    "links":[
    {
        "href":"https://sandbox.api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8",
        "rel":"Self",
        "method":"Get"
    }]}

Obs: The response of execute payment has only a link that you can get the specified transaction.

####2.1.4.EXECUTE PAYMENT

To execute a payment you must make a PUT request in /payments/{transactionId}/execute resource, where {transactionId} is the identifier of a previously created and approved payment transaction.

The following is an example PUT request to execute a payment:

PUT /payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/execute HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

The following is the sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8 

{
    "id":"0cf4e997-2c5d-4bf3-8238-1c4915c5cada",
    "links":[
    {
        "href":"https://api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8",
        "rel":"Self",
        "method":"Get"
    }]
}

Obs: The response of execute payment has only a link that you can get the specified transaction.

##3.Recurring Payments

###3.1.Getting a RecurringToken

In order to make a recurring payment you must first authenticate the relationship between your application and the client. This is a two steps process and your application must have recurring payments permissions:

AUTHENTICATION

First collect user identifier and pass it to InPDV.

The following is a PUT request example to generate an authentication OTPassword for the user.

PUT /recurring/+5511XXXXXXXXX HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

The expected response is:

HTTP/1.1 200 OK

AUTHORIZATION

After the authentication request, you need to collect the one-time password from the client in order to authorize and generate a recurring token for your application

The following is a POST request example to authorize your application in order to get the recurring token.

POST /recurring/authorize/+5511XXXXXXXXX HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…
Content-Length: 8

“ClientOTP”

The following is the sample response:

HTTP/1.1 200 OK
Content-Length: 130
Content-Type: application/json; charset=utf-8
… 
  
"2348f9d3e20f29f7cf0a964dd2d3edb359c86f497f8b12f13b6e5c9a8c3be374c491afa7f516c13629a47c2e03ce93d3392beab3a2e5a7150b7776fb9f3722f0"

Obs: The recurringToken of the user must be passed on whenever you want to make a recurring payment

###3.2.Payment using a RecurringToken

Having the recurring Token of the user, making and executing a payment become simple, all you need to do is pass the purchase information and recurring token to the InPDV API.

PAYMENT

The following POST is an example of request to create and execute a new payment using the recurring method.

POST /recurring/payment HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…
  
{
    “brandId”: 1,
    “identifier”: “+5511XXXXXXXXX”,
    “recurringToken”: “185ac379da056f769ab594b77f143c0083916388dcdd14746…”,
    “transaction”: 
    {
        “amount”: 1.99,
        “currencyCode”: “BRL”,
        “description”: “Product X”
    }
}

Obs:The parameters “brandId” and “currencyCode” are optional. Obs2:The parameter “identifier” is a user phone number in E.164 format. e.g., +5511999999999

The following is the sample response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
 
{
    "id":"0cf4e997-2c5d-4bf3-8238-1c4915c5cada",
    "links":[
    {
        "href":"https://api.sandbox.inpdv.com.br/payments/5578a3ae-ee7f-4ed8-9e56-529da9f263d8",
        "rel":"Self",
        "method":"Get"
    }]
}

The response of recurring payment has only a link where you can get the specified transaction.

###3.3.Cancelling a RecurringToken

If for some reason the client or your application need to end the Recurring relationship all you need to do is make a single PUT request. Once the RecurringToken is canceled he can't be used anymore, but if you want you can create a new one by re-doing the 3.1 process

PUT /recurring/cancel/+5531XXXXXXXXX HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…
  

The expected response is:

HTTP/1.1 200 OK

##4.Chargebacks

To execute a chargeback transaction you must make a GET request in /chargebacks/{transactionId} resource, where {transactionId} is the identifier of a previously executed transaction.

The following is an example GET request to execute a chargeback.

GET /chargebacks/5578a3ae-ee7f-4ed8-9e56-529da9f263d8 HTTP/1.1
Host: api.sandbox.inpdv.com.br 
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

Partial Chargeback

You can also execute a partial chargeback. The request is very similar but you need to inform our API the amount you want to chargeback:

PUT /chargebacks/5578a3ae-ee7f-4ed8-9e56-529da9f263d8/partial HTTP/1.1
Host: api.sandbox.inpdv.com.br
Content-Type: application/json; charset=utf-8
Authorization: Bearer BNACateSkXmuLt5wKCp2PktcYYMRH5zZtugL0L4WeCpu1079Am…

"25.52"

The same transaction may have any number of partial chargebacks you want, but the sum of their amounts must be equal or lower than the original transaction.

#API RESOURCE REFERENCE For resources below use as base API URL https://api.sandbox.inpdv.com.br

##1.Authentications

##2.Payment Only authenticated user can do this.

##3.Recurring

Only special authenticated user can do this.

##4.Chargeback

Only authenticated user can do this.

#Contact [email protected]