Recurring payments - API
Note
Recurring payments has been deprecated and it is not offered for commerces.How does it work?
Consider
Recurring payments is only available for accounts in Brazil, Colombia, Peru, and Mexico.To ensure proper use of the system, all requests must contain the HTTP authorization header with the shop’s credentials, so that it can be identified who is making the request. For this implementation basic authorization will be used, where the username (API Login) and password (API Key) are sent.
These are the data to be sent in the header of the request: The data pass an encrypted base 64 with the format: API Login : API Key
For example, if the API Login is 0123ABCDEF
and the API Key is A1B2C3D4E5
, then the Authorization header would be:
Authorization: Basic <base64 of 0123ABCDEF:A1B2C3D4E5>
Authorization: Basic MDEyM0FCQ0RFRjpBMUIyQzNENEU1
POST /payments-api/4.0/service.cgi HTTP/1.1
Host: sandbox.api.payulatam.com
Content-Type: application/json; charset=utf-8
Accept: application/json
Accept-language: es
Content-Length: length
Authorization: Basic MDEyM0FCQ0RFRjpBMUIyQzNENEU1
Pointing to the relevant URLs:
API
- Test:
https://sandbox.api.payulatam.com/payments-api/
- Production:
https://api.payulatam.com/payments-api/
The available methods for recurring payments are: PLAN, CUSTOMER, CREDIT CARD, SUBSCRIPTION and ADDITIONAL CHARGES. Below is a description of each.
1. Plan
Variables used for the creation of a plan
Field name | Format | Size | Description | Mandatory |
---|---|---|---|---|
planCode | Alphanumeric | Min: 1 Max: 255 | Unique code assigned by the merchant to the plan in order to identify it. | All countries |
description | Alphanumeric | Min: 1 Max: 255 | Plan description. | All countries |
accountId | Numeric | The identifier of the account to which the plan will be associated. | All countries | |
interval | Alphanumeric | Min: 3 Max: 5 | Interval that defines how often the subscription payment is performed. The possible values are: DAY , WEEK , MONTH , and YEAR . |
All countries |
intervalCount | Numeric | Interval count that defines how often the subscription payment is performed. | All countries | |
maxPaymentsAllowed | Numeric | Total amount of payments for the subscription. | All countries | |
maxPaymentAttempts | Numeric | Max: 3 | Total amount of payment attempts performed when a subscription payment is declined. | No |
paymentAttemptsDelay | Numeric | Total amount of waiting days between the payment attempts of the subscription. | All countries | |
maxPendingPayments | Numeric | Total amount of pending payments that a subscription can have before it is cancelled. | No | |
trialDays | Numeric | Total amount of trial days of the subscription. | No | |
additionalValues.entry.name | Alphanumeric | Min: 1 Max: 255 | The type of amount associated to the plan. The possible values are:
|
A node for each type. All countries |
additionalValues.entry.value | Numeric | 19, 2 | Plan value, tax or tax return base according to the additionalValue.entry.name. | All countries |
additionalValues.entry.currency | Alphanumeric | 3 | The ISO currency code associated with the amount. See Accepted currencies. | All countries |
Using this feature you can register a recurring plan and thus get its identifier.
The following operations are available:
URL | Method | Description |
---|---|---|
/rest/v4.3/plans | POST |
Creating a new plan for subscriptions associated with the merchant. |
/rest/v4.3/plans/{planCode} | PUT |
Update information about a plan for subscriptions.{planCode} : Plan’s identification code for the merchant. |
/rest/v4.3/plans/{planCode} | GET |
Check all the information of a plan for subscriptions associated with the merchant.{planCode} : Plan’s identification code for the merchant |
/rest/v4.3/plans/{planCode} | DELETE |
Delete an entire subscription plan associated with the merchant.{planCode} : Plan’s identification code for the merchant. |
Creation
Request body:
{
"accountId": "512321",
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"interval": "MONTH",
"intervalCount": "1",
"maxPaymentsAllowed": "12",
"paymentAttemptsDelay": "1",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": "20000",
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": "1600",
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": "8400",
"currency": "COP"
}
]
}
Response body:
{
"id": "b3d406d0-abd4-473c-a557-25aa81ff9032",
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": "512321",
"intervalCount": 1,
"interval": "MONTH",
"maxPaymentsAllowed": 12,
"maxPaymentAttempts": 0,
"paymentAttemptsDelay": 1,
"maxPendingPayments": 0,
"trialDays": 0,
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 20000,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 8400,
"currency": "COP"
}
]
}
Request body:
<plan>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<maxPendingPayments>0</maxPendingPayments>
<trialDays>30</trialDays>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
Response body:
<plan>
<id>0b63bd6d-9a2b-4c40-a314-a70a6bae27e3</id>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<maxPendingPayments>0</maxPendingPayments>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<trialDays>30</trialDays>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
Update
Request body:
{
"planCode": "sample-plan-code-001",
"description": "New Sample Plan 001",
"paymentAttemptsDelay": "3",
"maxPendingPayments": "1",
"maxPaymentAttempts": "1",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": "10000",
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": "0",
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": "0",
"currency": "COP"
}
]
}
Response body:
{
"id": "6b104e86-d6ca-41b5-ae39-834a55ed1565",
"planCode": "sample-plan-code-001",
"description": "New Sample Plan 001",
"accountId": "512321",
"intervalCount": 1,
"interval": "MONTH",
"maxPaymentsAllowed": 12,
"maxPaymentAttempts": 1,
"paymentAttemptsDelay": 3,
"maxPendingPayments": 1,
"trialDays": 0,
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
]
}
Request body:
<plan>
<description>New Sample Plan 001</description>
<maxPaymentAttempts>3</maxPaymentAttempts>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<maxPendingPayments>1</maxPendingPayments>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
Response body:
<plan>
<id>6b104e86-d6ca-41b5-ae39-834a55ed1565</id>
<planCode>sample-plan-code-001</planCode>
<description>New Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<maxPendingPayments>1</maxPendingPayments>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<trialDays>0</trialDays>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
Query
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/plans/sample-plan-code-001
Response body:
{
"id": "2a852bf2-ce67-4920-b9a6-66af2c68b4ae",
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": 1,
"intervalCount": 1,
"interval": "MONTH",
"maxPaymentsAllowed": 12,
"maxPaymentAttempts": 3,
"paymentAttemptsDelay": 1,
"maxPendingPayments": 0,
"trialDays": 30,
"additionalValues": [
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_VALUE",
"value": 20000,
"currency": "COP"
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/plans/sample-plan-code-001
Response body:
<plan>
<id>2a852bf2-ce67-4920-b9a6-66af2c68b4ae</id>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>1</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<maxPendingPayments>0</maxPendingPayments>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<trialDays>30</trialDays>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
Deletion
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/plans/sample-plan-code-001
Response body:
HTTP STATUS: 200 OK
2. Customer
Variables used for the creation of a customer
Field name | Format | Size | Description | Mandatory |
---|---|---|---|---|
fullName | Alphanumeric | Max: 255 | Customer’s complete name. | All countries |
Alphanumeric | Max: 255 | Customer’s email address. | All countries |
A customer is the unit that identifies who will be the beneficiary of a provided product or service and who is associated with a recurring payment plan.
The following operations are available:
URL | Method | Description |
---|---|---|
/rest/v4.3/customers/ | POST |
Creation of a customer in the system. |
/rest/v4.3/customers/{customerId} | PUT |
Updates the customer’s information in the system.{customerId} : Identifier of the client to be updated. |
/rest/v4.3/customers/{customerId} | GET |
Queries the information related to the customer.{customerId} : Identifier of the client from which you want to find the associated information. |
/rest/v4.3/customers/{customerId} | DELETE |
Removes a user from the system.{customerId} : Identifier of the client to be deleted. |
Creation
Request body:
{
"fullName": "Pedro E. Perez",
"email": "pperez@payulatam.com"
}
Response body:
{
"id": "6ahxar252",
"fullName": "Pedro E. Perez",
"email": "pperez@payulatam.com"
}
Request body:
<customer>
<fullName>Pedro E. Perez</fullName>
<email>pperez@payulatam.com</email>
</customer>
Response body:
<customer>
<id>6ahxar252</id>
<fullName>Pedro E. Pérez</fullName>
<email>pperez@payulatam.com</email>
</customer>
Update
Request body:
{
"fullName": "Pedro E. Perez",
"email": "pperez@payulatam.com"
}
Response body:
{
"id": "6ahxar252",
"fullName": "Pedro E. Perez",
"email": "pperez@payulatam.com"
}
Request body:
<customer>
<fullName>Pedro E. Perez</fullName>
<email>pperez@payulatam.com</email>
</customer>
Response body:
<customer>
<id>6ahxar252</id>
<fullName>Pedro E. Pérez</fullName>
<email>pperez@payulatam.com</email>
</customer>
Query
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/customers/2mkls9xekm
Response body:
{
"id": "2mkls9xekm",
"fullName": "Pedro Perez",
"email": "pperez@payulatam.com",
"creditCards": [
{
"token": "da2224a9-58b7-482a-9866-199de911c23f",
"customerId": "2mkls9xekm",
"number": "************4242",
"name": "Usuario Prueba",
"type": "VISA",
"address": {
"line1": "Street 93B",
"line2": "17 25",
"line3": "Office 301",
"city": "Bogota",
"country": "CO",
"postalCode": "00000",
"phone": "300300300"
}
}
],
"subscriptions": [
{
"id": "2mlhk3qxji",
"quantity": "1",
"installments": "1",
"currentPeriodStart": "2013-08-30T10:46:41.477-05:00",
"currentPeriodEnd": "2013-09-29T10:46:41.477-05:00",
"plan": {
"id": "414215a2-c990-4525-ba84-072181988d09",
"planCode": "PLAN-REST-16",
"description": "Plan rest test",
"accountId": "1",
"intervalCount": "1",
"interval": "MONTH",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": "20000",
"currency": "COP"
}
]
}
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/customers/2mkls9xekm
Response body:
<customer>
<id>2mkls9xekm</id>
<fullName>Pedro Perez</fullName>
<email>pperez@payulatam.com</email>
<creditCards>
<creditCard>
<token>da2224a9-58b7-482a-9866-199de911c23f</token>
<customerId>2mkls9xekm</customerId>
<number>************4242</number>
<name>Usuario Prueba</name>
<type>VISA</type>
<address>
<line1>Calle 93B</line1>
<line2>17 25</line2>
<line3>Oficina 301</line3>
<city>Bogota</city>
<country>CO</country>
<postalCode>00000</postalCode>
<phone>300300300</phone>
</address>
</creditCard>
</creditCards>
<subscriptions>
<subscription>
<id>2mlhk3qxji</id>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2013-08-30T10:46:41.477-05:00</currentPeriodStart>
<currentPeriodEnd>2013-09-29T10:46:41.477-05:00</currentPeriodEnd>
<plan>
<id>414215a2-c990-4525-ba84-072181988d09</id>
<planCode>PLAN-REST-16</planCode>
<description>Plan rest test</description>
<accountId>1</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
</subscriptions>
</customer>
Deletion
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/customers/7wp1r0atl
Response body:
{
"description": "El cliente [7wp1r0atl] ha sido eliminado."
}
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/customers/7wp1r0atl
Response body:
<response>
<description>El cliente [7wp1r0atl] ha sido eliminado</description>
</response>
3. Credit card
Variables used for the creation of a credit card
Field name | Format | Size | Description | Mandatory |
---|---|---|---|---|
number | Numeric | Min: 13 Max: 20 | Credit card number. | All countries |
name | Alphanumeric | Min: 1 Max: 255 | Full name of the credit card holder as shown in the credit card. | All countries |
document | Alphanumeric | Min: 5 Max: 30 | Identification number of the credit card holder. | All countries |
expMonth | Numeric | Min: 1 Max: 12 | Credit card’s expiration month. | All countries |
expYear | Numeric | Min: 00 Max: 2999 | Credit card’s expiration year. If it is a two digit value, it represents the years between 2000 (00) and 2099 (99). It the value has more than two digits it is used literally, being 2000 the minimum value. | All countries |
type | Alphanumeric | The franchise or credit card type. See Payment method. | All countries | |
address | Credit card holder’s billing address, associated to the credit card. | All countries | ||
address.line1 | Alphanumeric | Min: 1 Max: 100 | First line of the address. | All countries |
address.line2 | Alphanumeric | Min: 1 Max: 100 | Second line of the address or street number. | No |
address.line3 | Alphanumeric | Min: 1 Max: 100 | Third line of the address. | No |
address.city | Alphanumeric | Min: 1 Max: 50 | City. | All countries |
address.state | Alphanumeric | Min: 1 Max: 40 | State or department. *For Brazil send only 2 characters. Example: For Sao Paulo, send SP. | Brazil |
address.country | Alphanumeric | 2 | Country of the address in format ISO 3166 Alfa 2 code. | All countries |
address.postalCode | Alphanumeric | Min: 1 Max: 20 | Postal code of the address. *For Brazil use the format XXXXX-XXX or XXXXXXXX, for example: 09210-710 o 09210710. | Mexico, Brazil |
address.phone | Alphanumeric | Min: 1 Max: 20 | Phone associated to the address. *For Brazil use the format ddd(2)+number(7-9), for example: (11)756312633. | All countries |
It is the payment method that relates a customer to a plan. It is composed of the credit card number (that will be tokenized to store data securely), the expiration date of the card and some additional address data.
The following operations are available:
URL | Method | Description |
---|---|---|
/rest/v4.3/customers/{customerID}/creditCards | POST |
Creating a credit card (Token) and assigning it to a user.{customerId} : Identifier of the client with whom you are going to associate the token with. |
/rest/v4.3/creditCards/{creditCardId} | PUT |
Update a token’s information.{creditCardId} : Identifier of the token to be updated. |
/rest/v4.3/creditCards/{creditCardId} | GET |
Check the information of a credit card (Token) data identifier.{creditCardId} : Credit Card Token you want to consult. |
/rest/v4.3/customers/{customerID}/creditCards/{creditCardId} | DELETE |
Delete a credit card (Token) associated with a user.{customerId} : Identifier of the client of whom you are going to delete the token.{creditCardId} : Identifier of the token to be deleted. |
Creation
Request body:
{
"name": "Sample User Name",
"document": "1020304050",
"number": "4242424242424242",
"expMonth": "01",
"expYear": "2018",
"type": "VISA",
"address": {
"line1": "Address Name",
"line2": "17 25",
"line3": "Of 301",
"postalCode": "00000",
"city": "City Name",
"state": "State Name",
"country": "CO",
"phone": "300300300"
}
}
Response body:
{
"token": "8186ca42-2f69-417b-94a0-208bd8e089af"
}
Request body:
<creditCard>
<name>Sample User Name</name>
<document>1020304050</document>
<number>4242424242424242</number>
<expMonth>01</expMonth>
<expYear>2018</expYear>
<type>VISA</type>
<address>
<line1>Address Name</line1>
<line2>17 25</line2>
<line3>Of 301</line3>
<postalCode>00000</postalCode>
<city>City Name</city>
<state>State Name</state>
<country>CO</country>
<phone>300300300</phone>
</address>
</creditCard>
Response body:
<creditCard>
<token>8186ca42-2f69-417b-94a0-208bd8e089af</token>
</creditCard>
Update
Request body:
{
"expMonth": "12",
"expYear": "2016",
"name": "Sample user name",
"document": "65858645",
"address": {
"line1": "Sample Address",
"line2": "Cll 93 B",
"line3": "Ofic. 301",
"postalCode": "00000",
"city": "city",
"country": "CO",
"state": "state",
"phone": "2266758"
}
}
Response body:
{
"token": "a068e980-a6d7-4a19-b549-75c04f39ec22",
"customerId": "eab38z33hh2",
"number": "424242******4242",
"type": "VISA",
"name": "Sample user name",
"document": "65858645",
"address": {
"line1": "Sample Address",
"line2": "Cll 93 B",
"line3": "Ofic. 301",
"city": "city",
"state": "state",
"country": "CO",
"postalCode": "00000",
"phone": "2266758"
}
}
Request body:
<creditCard>
<expMonth>12</expMonth>
<expYear>2016</expYear>
<name>Sample user name</name>
<document>65858645</document>
<address>
<line1>Sample Address</line1>
<line2>Cll 93 B</line2>
<line3>Ofic. 301</line3>
<postalCode>00000</postalCode>
<city>city</city>
<country>CO</country>
<state>state</state>
<phone>2266758</phone>
</address>
</creditCard>
Response body:
<creditCard>
<token>a068e980-a6d7-4a19-b549-75c04f39ec22</token>
<customerId>eab38z33hh2</customerId>
<number>424242******4242</number>
<name>Sample user names</name>
<document>65858645</document>
<type>VISA</type>
<address>
<line1>Sample Addresss</line1>
<line2>Cll 93 B</line2>
<line3>Ofic. 301</line3>
<city>city</city>
<state>state</state>
<country>CO</country>
<postalCode>00000</postalCode>
<phone>2266758</phone>
</address>
</creditCard>
Query
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/customers/2mkls9xekm
Response body:
{
"token": "256f8e39-e37c-4ff3-9b5f-63937ee5c69c",
"customerId": "5whjhimjtpn",
"number": "424242******4242",
"type": "VISA",
"name": "Sample User Name",
"document": "1020304050",
"address": {
"line1": "Address Name",
"line2": "17 25",
"line3": "Of 301",
"city": "City Name",
"state": "State Name",
"country": "CO",
"postalCode": "00000",
"phone": "300300300"
}
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/customers/2mkls9xekm
Response body:
<creditCard>
<token>8186ca42-2f69-417b-94a0-208bd8e089af</token>
<customerId>11sgnt8s19</customerId>
<number>************4242</number>
<name>Sample User Name</name>
<type>VISA</type>
<address>
<line1>Address Name</line1>
<line2>17 25</line2>
<line3>Of 301</line3>
<city>City Name</city>
<state>State Name</state>
<country>CO</country>
<postalCode>00000</postalCode>
<phone>300300300</phone>
</address>
</creditCard>
Deletion
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/customers/{customerID}/creditCards/{creditCardId}
Response body:
{
"description": "La tarjeta de crédito f17e9c5c-c414-4dc0-a145-5b0647f7dbf8 se ha eliminado exitosamente"
}
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/customers/{customerID}/creditCards/{creditCardId}
Response body:
<response>
<description>La tarjeta de crédito f17e9c5c-c414-4dc0-a145-5b0647f7dbf8 se ha eliminado exitosamente</description>
</response>
4. Subscription
Variables used for the creation of a subscription
Field name | Format | Size | Description | Mandatory |
---|---|---|---|---|
quantity | Numeric | Total amount of plans that will be acquired with the subscription. | No | |
installments | Numeric | Total amount of installments to defer the payment. | No | |
trialDays | Numeric | Total amount of trial days of the subscription. This variable has preference over the plan’s trial days. | No | |
customer | Customer that will be associated to the subscription. You can find more information in the “Customer” section of this page. | All countries | ||
customer.creditCards | Customer’s credit card that is selected to make the payment. You can find more information in the “Credit card” section of this page. | All countries | ||
plan | Plan that will be associated to the subscription. You can find more information in the “Plan” section of this page. | All countries |
A subscription is the relationship between a payment plan, a payer and a credit card. It is the element that controls the execution of the respective collections.
The following operations are available:
URL | Methods | Description |
---|---|---|
/rest/v4.3/subscriptions/ | POST |
Creating a new subscription of a client to a plan. |
/rest/v4.3/subscriptions/{subscriptionId} | PUT |
Update information associated with the specified subscription. At the moment it is only possible to update the token of the credit card to which the charge of the subscription is made.{subscriptionId} : Identification of the subscription. |
/rest/v4.3/subscriptions/{subscriptionId} | GET |
Check the basic information associated with the specified subscription.{subscriptionId} : Identification of the subscription. |
/rest/v4.3/subscriptions/{subscriptionId} | DELETE |
Unsubscribe, delete the relationship of the customer with the plan.{subscriptionId} : Identification of the subscription. |
Creation
With all new items
Request body:
{
"quantity": "1",
"installments": "1",
"trialDays": "15",
"customer": {
"fullName": "Pedro Perez",
"email": "pperez@payulatam.com",
"creditCards": [
{
"name": "Pedro Perez",
"document": "101010123",
"number": "4242424242424242",
"expMonth": "01",
"expYear": "2018",
"type": "VISA",
"address": {
"line1": "Address Name",
"line2": "17 25",
"line3": "Of 301",
"postalCode": "00000",
"city": "City Name",
"state": "State Name",
"country": "CO",
"phone": "300300300"
}
}
]
},
"plan": {
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": "512321",
"intervalCount": "1",
"interval": "MONTH",
"maxPaymentsAllowed": "12",
"maxPaymentAttempts": "3",
"paymentAttemptsDelay": "1",
"maxPendingPayments": "1",
"trialDays": "30",
"additionalValues": [
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 8400,
"currency": "COP"
}
]
}
}
Response body:
{
"id": "563cbd0o54z",
"plan": {
"id": "145ad747-adeb-43db-80c0-447c8f7ad8b4",
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": "512321",
"intervalCount": 1,
"interval": "MONTH",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 8400,
"currency": "COP"
}
]
},
"customer": {
"id": "a39e3zvsru6",
"fullName": "Pedro Perez",
"email": "pperez@payulatam.com",
"creditCards": [
{
"token": "7b6d637a-6252-47ee-8d3b-ed91807b3146"
}
]
},
"quantity": "1",
"installments": "1",
"currentPeriodStart": 1402203600000,
"currentPeriodEnd": 1404795599000
}
Request body:
<subscription>
<trialDays>30</trialDays>
<installments>1</installments>
<customer>
<fullName>Pedro Perez</fullName>
<email>pperezz@payulatam.com</email>
<creditCards>
<creditCard>
<number>4242424242424242</number>
<name>Sample User Name</name>
<expMonth>1</expMonth>
<expYear>2018</expYear>
<type>VISA</type>
<address>
<line1>Address Name</line1>
<line2>17 25</line2>
<line3>Of 301</line3>
<city>City Name</city>
<state>State Name</state>
<country>CO</country>
<postalCode>00000</postalCode>
<phone>300300300</phone>
</address>
</creditCard>
</creditCards>
</customer>
<plan>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<maxPendingPayments>1</maxPendingPayments>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
Response body:
<subscription>
<id>26fb7yxfej0</id>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-23T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-22T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>047dbnhsnx9</id>
<fullName>Pedro Perez</fullName>
<email>pperezz@payulatam.com</email>
<creditCards>
<creditCard>
<token>daedc017-bd7d-4887-87b4-13913650c952</token>
</creditCard>
</creditCards>
</customer>
<plan>
<id>77e57940-e149-4f77-a190-271caa7ccb7b</id>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<additionalValues>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
With all existing elements
Request body:
{
"quantity": "1",
"installments": "1",
"trialDays": "10",
"customer": {
"id": "eab38z33hh2",
"creditCards": [
{
"token": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
]
},
"plan": {
"planCode": "sample-plan-code-001"
}
}
Response body:
{
"id": "fb6d0m9nqb8",
"plan": {
"id": "6b104e86-d6ca-41b5-ae39-834a55ed1565",
"planCode": "sample-plan-code-001",
"description": "New Sample Plan 001",
"accountId": 512321,
"intervalCount": 1,
"interval": "MONTH",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 0,
"currency": "COP"
}
]
},
"customer": {
"id": "eab38z33hh2",
"fullName": "Pedro Perez",
"email": "pperez@payulatam.com",
"creditCards": [
{
"token": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
]
},
"quantity": 1,
"installments": 1,
"trialDays": "30",
"currentPeriodStart": 1397192400000,
"currentPeriodEnd": 1428728399000
}
Request body:
<subscription>
<quantity>1</quantity>
<installments>1</installments>
<trialDays>10</trialDays>
<customer>
<id>eab38z33hh2</id>
<creditCards>
<creditCard>
<token>a068e980-a6d7-4a19-b549-75c04f39ec22</token>
</creditCard>
</creditCards>
</customer>
<plan>
<planCode>sample-plan-code-001</planCode>
</plan>
</subscription>
Response body:
<subscription>
<id>fb6d0m9nqb8</id>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-03T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-02T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>eab38z33hh2</id>
<fullName>Pedro Perez</fullName>
<email>pperezz@payulatam.com</email>
<creditCards>
<creditCard>
<token>a068e980-a6d7-4a19-b549-75c04f39ec22</token>
</creditCard>
</creditCards>
</customer>
<plan>
<id>6b104e86-d6ca-41b5-ae39-834a55ed1565</id>
<planCode>sample-plan-code-001</planCode>
<description>New Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
With plan and client already created, and a new card
Request body:
{
"quantity": "1",
"installments": "1",
"trialDays": "10",
"customer": {
"id": "eab38z33hh2",
"creditCards": [
{
"name": "Sample User Name",
"document": "101010123",
"number": "4242424242424242",
"expMonth": "01",
"expYear": "2018",
"type": "VISA",
"address": {
"line1": "Address Name",
"line2": "17 25",
"line3": "Of 301",
"postalCode": "00000",
"city": "City Name",
"state": "State Name",
"country": "CO",
"phone": "300300300"
}
}
]
},
"plan": {
"planCode": "sample-plan-code-001"
}
}
Response body:
{
"id": "c50d94ge25d",
"plan": {
"id": "6b104e86-d6ca-41b5-ae39-834a55ed1565",
"planCode": "sample-plan-code-001",
"description": "New Sample Plan 001",
"accountId": "512321",
"intervalCount": 1,
"interval": "MONTH",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
]
},
"customer": {
"id": "eab38z33hh2",
"fullName": "Pedro Perez",
"email": "pperezz@payulatam.com",
"creditCards": [
{
"token": "508a715f-2feb-46ba-8945-c948821f080e"
}
]
},
"quantity": "1",
"installments": "1",
"currentPeriodStart": 1401771600000,
"currentPeriodEnd": 1404363599000
}
Request body:
<subscription>
<trialDays>10</trialDays>
<installments>1</installments>
<customer>
<id>eab38z33hh2</id>
<creditCards>
<creditCard>
<number>4242424242424242</number>
<name>Sample User Name</name>
<expMonth>1</expMonth>
<expYear>2018</expYear>
<type>VISA</type>
<address>
<line1>Address Name</line1>
<line2>17 25</line2>
<line3>Of 301</line3>
<city>City Name</city>
<state>State Name</state>
<country>CO</country>
<postalCode>00000</postalCode>
<phone>300300300</phone>
</address>
</creditCard>
</creditCards>
</customer>
<plan>
<planCode>sample-plan-code-001</planCode>
</plan>
</subscription>
Response body:
<subscription>
<id>40adcwryufe</id>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-03T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-02T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>eab38z33hh2</id>
<fullName>Pedro Perez</fullName>
<email>pperezz@payulatam.com</email>
<creditCards>
<creditCard>
<token>508a715f-2feb-46ba-8945-c948821f080e</token>
</creditCard>
</creditCards>
</customer>
<plan>
<id>6b104e86-d6ca-41b5-ae39-834a55ed1565</id>
<planCode>sample-plan-code-001</planCode>
<description>New Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
Customer and card already created, and with a new plan
Request body:
{
"installments": "1",
"trialDays": "30",
"customer": {
"id": "eab38z33hh2",
"creditCards": [
{
"token": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
]
},
"plan": {
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": "512321",
"intervalCount": "1",
"interval": "MONTH",
"maxPaymentsAllowed": "12",
"maxPaymentAttempts": "3",
"paymentAttemptsDelay": "1",
"maxPendingPayments": "1",
"trialDays": "30",
"additionalValues": [
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 8400,
"currency": "COP"
}
]
}
}
Response body:
{
"id": "320756yk1x0",
"plan": {
"id": "68ee02fa-8d1e-4bc3-88fb-b6e66586df3b",
"planCode": "sample-plan-code-001",
"description": "Sample Plan 001",
"accountId": "512321",
"intervalCount": 1,
"interval": "MONTH",
"additionalValues": [
{
"name": "PLAN_VALUE",
"value": 10000,
"currency": "COP"
},
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_TAX_RETURN_BASE",
"value": 8400,
"currency": "COP"
}
]
},
"customer": {
"id": "eab38z33hh2",
"fullName": "Pedro Perez",
"email": "pperezz@payulatam.com",
"creditCards": [
{
"token": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
]
},
"quantity": "1",
"installments": "1",
"currentPeriodStart": 1403499600000,
"currentPeriodEnd": 1406091599000
}
Request body:
<subscription>
<trialDays>30</trialDays>
<installments>1</installments>
<customer>
<id>eab38z33hh2</id>
<creditCards>
<creditCard>
<token>a068e980-a6d7-4a19-b549-75c04f39ec22</token>
</creditCard>
</creditCards>
</customer>
<plan>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<maxPaymentsAllowed>12</maxPaymentsAllowed>
<maxPaymentAttempts>3</maxPaymentAttempts>
<maxPendingPayments>1</maxPendingPayments>
<paymentAttemptsDelay>1</paymentAttemptsDelay>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
Response body:
<subscription>
<id>17d11h3b2xs</id>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-23T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-22T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>eab38z33hh2</id>
<fullName>Pedro Perez</fullName>
<email>pperezz@payulatam.com</email>
<creditCards>
<creditCard>
<token>a068e980-a6d7-4a19-b549-75c04f39ec22</token>
</creditCard>
</creditCards>
</customer>
<plan>
<id>c653e0ba-e0cb-49d9-9294-1d5617be8f6c</id>
<planCode>sample-plan-code-001</planCode>
<description>Sample Plan 001</description>
<accountId>512321</accountId>
<intervalCount>1</intervalCount>
<interval>MONTH</interval>
<additionalValues>
<additionalValue>
<name>PLAN_TAX</name>
<value>1600</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>PLAN_TAX_RETURN_BASE</name>
<value>8400</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</plan>
</subscription>
Update (Credit card of a subscription)
Request body:
{
"creditCardToken": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
Response body:
{
"id": "320756yk1x0",
"plan": {
"id": "68ee02fa-8d1e-4bc3-88fb-b6e66586df3b"
},
"customer": {
"id": "eab38z33hh2"
},
"trialDays": "30",
"quantity": "1",
"installments": "1",
"currentPeriodStart": 1403499600000,
"currentPeriodEnd": 1406091599000,
"creditCardToken": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
Request body:
<subscription>
<creditCardToken>a068e980-a6d7-4a19-b549-75c04f39ec22</creditCardToken>
</subscription>
Response body:
<subscription>
<id>320756yk1x0</id>
<trialDays>30</trialDays>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-23T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-22T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>eab38z33hh2</id>
</customer>
<plan>
<id>68ee02fa-8d1e-4bc3-88fb-b6e66586df3b</id>
</plan>
<creditCardToken>a068e980-a6d7-4a19-b549-75c04f39ec22</creditCardToken>
</subscription>
Query
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/subscriptions/1dhb51hfuu
Response body:
{
"id": "320756yk1x0",
"plan": {
"id": "68ee02fa-8d1e-4bc3-88fb-b6e66586df3b"
},
"customer": {
"id": "eab38z33hh2"
},
"trialDays": "30",
"quantity": "1",
"installments": "1",
"currentPeriodStart": 1403499600000,
"currentPeriodEnd": 1406091599000,
"creditCardToken": "a068e980-a6d7-4a19-b549-75c04f39ec22"
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/subscriptions/1dhb51hfuu
Response body:
<subscription>
<id>320756yk1x0</id>
<trialDays>30</trialDays>
<quantity>1</quantity>
<installments>1</installments>
<currentPeriodStart>2014-06-23T00:00:00-05:00</currentPeriodStart>
<currentPeriodEnd>2014-07-22T23:59:59-05:00</currentPeriodEnd>
<customer>
<id>eab38z33hh2</id>
</customer>
<plan>
<id>68ee02fa-8d1e-4bc3-88fb-b6e66586df3b</id>
</plan>
<creditCardToken>a068e980-a6d7-4a19-b549-75c04f39ec22</creditCardToken>
</subscription>
Deletion
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/subscriptions/3hpyu04ij
Response body:
{
"description": "La suscripción [3hpyu04ij] ha sido cancelada"
}
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/subscriptions/3hpyu04ij
Response body:
<response>
<description>La suscripción [3hpyu04ij] ha sido cancelada</description>
</response>
5. Additional charges
Variables used for the creation of an additional charge
Field name | Format | Size | Description | Mandatory |
---|---|---|---|---|
descripcion | Alphanumeric | Min: 1 Max: 255 | Description of the additional charge associated to the payment. | All countries |
additionalValues.entry.name | Alphanumeric | Min: 1 Max: 255 | The type of amount associated to the additional charge. The possible values are:
|
A node for each type. All countries |
additionalValues.entry.value | Numeric | 19, 2 | Charge value, tax or tax return base according to the additionalValue.entry.name . |
All countries |
additionalValues.entry.currency | Alphanumeric | 3 | The ISO currency code associated to the amount. See Accepted currencies. | All countries |
A charge may be an additional charge or a discount realized on the value of one of the payments that comprise the recurring payment plan. These only affect the next pending item and run once.
The following operations are available:
URL | Methods | Description |
---|---|---|
/rest/v4.3/subscriptions/{subscriptionId}/recurringBillItems | POST |
Adds extra charges to the respective invoice for the current period.{subscriptionId} : Identification of the subscription |
/rest/v4.3/recurringBillItems/{recurringBillItemId} | PUT |
Updates the information from an additional charge in an invoice{recurringBillItemId} : Identifier of the additional charge. |
/rest/v4.3/recurringBillItems/{recurringBillItemId} | GET |
Query extra charge information of an invoice from its identifier.{recurringBillItemId} : Identifier of the additional charge |
/rest/v4.3/recurringBillItems/{recurringBillItemId} | DELETE |
Remove an extra charge from an invoice.{recurringBillItemId} : Identifier of the additional charge. |
/rest/v4.3/recurringBillItems/ | GET | Query extra charges of shop’s invoices that meet the stipulated filters. The available filters are shown below and should be sent as named parameters in the URL:{subscriptionId} : Identification of the subscription.{description} : Description entered in the extra charge. |
Creation
Request body:
{
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": "20000",
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": "0",
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": "0",
"currency": "COP"
}
]
}
Response body:
{
"id": "522023su5xg",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
],
"subscriptionId": "52b04sx2s6"
}
Request body:
<recurringBillItem>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
Response body:
<recurringBillItem>
<id>5e174m7lgns</id>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
<subscriptionId>52b04sx2s6</subscriptionId>
</recurringBillItem>
Update
Request body:
{
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": "20000",
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": "0",
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": "0",
"currency": "COP"
}
]
}
Response body:
{
"id": "5e174m7lgns",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
],
"subscriptionId": "52b04sx2s6"
}
Request body:
<recurringBillItem>
<isTest>false</isTest>
<id>5e174m7lgns</id>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
Response body:
<recurringBillItem>
<id>5e174m7lgns</id>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
<subscriptionId>52b04sx2s6</subscriptionId>
</recurringBillItem>
Query
By id of extra charge
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/2uww909obl
Response body:
{
"id": "5wm1pxmpiwq",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
}
],
"subscriptionId": "5wjxrja8mz9"
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/2uww909obl
Response body:
<recurringBillItem>
<id>2uww909obl</id>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_VALUE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
<additionalValue>
<name>ITEM_TAX_RETURN_BASE</name>
<value>0</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
By description of the extra charge
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/?description=Cargo%20b
Response body:
{
"recurringBillItemList": [
{
"id": "5vsags0qsdo",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
}
],
"subscriptionId": "5vsa272tek7"
},
{
"id": "5wm1pxmpiwq",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
],
"subscriptionId": "5wjxrja8mz9"
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/?description=Cargo%20b
Response body:
<recurringBillItemResponse>
<recurringBillItems>
<recurringBillItem>
<id>2waez3h9ac</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>15000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>24e207ivi</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000.49</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>26gzctvub</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000.49</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>2uxvargit1</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000.49</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>2uy01uio7o</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>10000.49</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>2ve0qtsjzz</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>15000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>2w16yddd98</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>15000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
</recurringBillItems>
</recurringBillItemResponse>
By subscription
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/?subscriptionId=26gyv192a
Response body:
{
"recurringBillItemList": [
{
"id": "5wjxrkgk7rc",
"description": "Custo do plano",
"additionalValues": [
{
"name": "PLAN_TAX",
"value": 1600,
"currency": "COP"
},
{
"name": "PLAN_VALUE",
"value": 20000,
"currency": "COP"
}
],
"subscriptionId": "5wjxrja8mz9"
},
{
"id": "5wm1pxmpiwq",
"description": "Cargo extra de prueba",
"additionalValues": [
{
"name": "ITEM_VALUE",
"value": 20000,
"currency": "COP"
},
{
"name": "ITEM_TAX",
"value": 0,
"currency": "COP"
},
{
"name": "ITEM_TAX_RETURN_BASE",
"value": 0,
"currency": "COP"
}
],
"subscriptionId": "5wjxrja8mz9"
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/?subscriptionId=26gyv192a
Response body:
<recurringBillItemResponse>
<recurringBillItems>
<recurringBillItem>
<id>2waez3h9ac</id>
<description>Cargo básico</description>
<additionalValues>
<additionalValue>
<name>PLAN_VALUE</name>
<value>15000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
<recurringBillItem>
<id>2uww909obl</id>
<description>Cargo extra de prueba</description>
<additionalValues>
<additionalValue>
<name>ITEM_VALUE</name>
<value>20000</value>
<currency>COP</currency>
</additionalValue>
</additionalValues>
</recurringBillItem>
</recurringBillItems>
</recurringBillItemResponse>
Deletion
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/ou8ru86nq
Response body:
{
"description": "recurring bill item ou8ru86nq has been removed successfully"
}
Request body:
DELETE https://api.payulatam.com/payments-api/rest/v4.3/recurringBillItems/ou8ru86nq
Response body:
<response>
<description>recurring bill item ou8ru86nq has been removed successfully</description>
</response>
6. Billing
Associated attributes to the bills
Field name | Format | Description |
---|---|---|
recurringBill.id | Alphanumeric | Bill id in the PayU platform. |
recurringBill.orderId | Numeric | Id of the order that is associated to the bill in the PayU platform. |
recurringBill.subscriptionId | Alphanumeric | Id of the subscription that is associated to the bill in the PayU platform. |
recurringBill.state | Alphanumeric | State of the payment. The possible values are:
|
recurringBill.amount | Numeric | Total amount of the payment. |
recurringBill.currency | Alphanumeric | The ISO currency code associated to the amount. See Accepted currencies. |
recurringBill.dateCharge | Date | Date of the payment. When the json format is used the value structure is Epoch/Unix, therefore it is necessary to convert it. |
A bill is a payment attempt performed over a subscription, or its execution is pending.
Billing only has the following query method available:
URL | Methods | Description |
---|---|---|
/rest/v4.3/recurringBill | GET |
Query the pill paid or pending. You can query by client, subscription, or date range:/rest/v4.3/recurringBill?customerId={customerId} /rest/v4.3/recurringBill?subscriptionId={subscriptionId} /rest/v4.3/recurringBill?customerId={customerId}&dateBegin;={dateBegin}&dateFinal;={dateFinal} |
Query
By id of the client
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?customerId=6dtc2i97hw5
Response body:
{
"recurringBillList": [
{
"id": "cc522b0e-af0b-4ece-978d-f5c5632caa52",
"orderId": 71516840,
"subscriptionId": "6dtg51j09cr",
"state": "PAID",
"amount": 10000,
"currency": "COP",
"dateCharge": 1391490000000
},
{
"id": "56f0f5ca-cf29-437e-8920-7bc35578a39f",
"subscriptionId": "6dtf4q8v451",
"state": "CANCELLED",
"amount": 10000,
"currency": "COP",
"dateCharge": 1392786000000
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?customerId=6dtc2i97hw5
Response body:
<recurringBillListResponse>
<recurringBills>
<recurringBill>
<id>cc522b0e-af0b-4ece-978d-f5c5632caa52</id>
<orderId>71516840</orderId>
<subscriptionId>6dtg51j09cr</subscriptionId>
<state>PAID</state>
<amount>10000</amount>
<currency>COP</currency>
<dateCharge>2014-02-04T00:00:00-05:00</dateCharge>
</recurringBill>
<recurringBill>
<id>56f0f5ca-cf29-437e-8920-7bc35578a39f</id>
<subscriptionId>6dtf4q8v451</subscriptionId>
<state>CANCELLED</state>
<amount>10000</amount>
<currency>COP</currency>
<dateCharge>2014-02-19T00:00:00-05:00</dateCharge>
</recurringBill>
</recurringBills>
</recurringBillListResponse>
By id of the subscription
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?subscriptionId=6dtg51j09cr
Response body:
{
"recurringBillList": [
{
"id": "cc522b0e-af0b-4ece-978d-f5c5632caa52",
"orderId": 71516840,
"subscriptionId": "6dtg51j09cr",
"state": "PAID",
"amount": 10000,
"currency": "COP",
"dateCharge": 1391490000000
},
{
"id": "528a91a5-19bf-4db5-9a4a-4ecd2f07056b",
"orderId": 71651340,
"subscriptionId": "6dtg51j09cr",
"state": "PAID",
"amount": 10000,
"currency": "COP",
"dateCharge": 1391576400000
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?subscriptionId=6dtg51j09cr
Response body:
<recurringBillListResponse>
<recurringBills>
<recurringBill>
<id>cc522b0e-af0b-4ece-978d-f5c5632caa52</id>
<orderId>71516840</orderId>
<subscriptionId>6dtg51j09cr</subscriptionId>
<state>PAID</state>
<amount>10000</amount>
<currency>COP</currency>
<dateCharge>2014-02-04T00:00:00-05:00</dateCharge>
</recurringBill>
<recurringBill>
<id>56f0f5ca-cf29-437e-8920-7bc35578a39f</id>
<orderId>71651340</orderId>
<subscriptionId>6dtg51j09cr</subscriptionId>
<state>PAID</state>
<amount>10000</amount>
<currency>COP</currency>
<dateCharge>2014-02-19T00:00:00-05:00</dateCharge>
</recurringBill>
</recurringBills>
</recurringBillListResponse>
By id of the client and a date range
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?customerId=6dtc2i97hw5&dateBegin;=2014-02-03&dateFinal;=2014-02-04
Response body:
{
"recurringBillList": [
{
"id": "cc522b0e-af0b-4ece-978d-f5c5632caa52",
"orderId": 71516840,
"subscriptionId": "6dtg51j09cr",
"state": "PAID",
"amount": 10000,
"currency": "COP",
"dateCharge": 1391490000000
}
]
}
Request body:
GET https://api.payulatam.com/payments-api/rest/v4.3/recurringBill?customerId=6dtc2i97hw5&dateBegin;=2014-02-03&dateFinal;=2014-02-04
Response body:
<recurringBillListResponse>
<recurringBills>
<recurringBill>
<id>cc522b0e-af0b-4ece-978d-f5c5632caa52</id>
<orderId>71516840</orderId>
<subscriptionId>6dtg51j09cr</subscriptionId>
<state>PAID</state>
<amount>10000</amount>
<currency>COP</currency>
<dateCharge>2014-02-04T00:00:00-05:00</dateCharge>
</recurringBill>
</recurringBills>
</recurringBillListResponse>