Recurring payments - API

Recurring payments are automated payments that are carried out periodically (daily, monthly, annually), of those consumption charges of goods or services such as memberships, subscriptions, policies or receipts with fixed value; that were previously authorized by the customer.

How does it work?

Concepts

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:

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:
  • PLAN_VALUE: total value of the plan.
  • PLAN_TAX_VALUE: tax value associated to the value of the plan.
  • PLAN_TAX_RETURN_BASE: tax return base value associated to the value of the plan.
 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
email 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:
  • ITEM_VALUE: total value of the additional charge.
  • ITEM_TAX: tax value associated to the value of the additional charge.
  • ITEM_TAX_RETURN_BASE: tax return base value associated to the value of the additional charge.
 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:
  • NOT_PAID: Declined payment.
  • PAYMENT_IN_PROGRESS: Payment in progress of charge.
  • PENDING: The next payment to charge.
  • RETRYING_PAYMENT: Retrying payment.
  • PAID: Approved payment.
  • CANCELLED: Cancelled subscription.
  • PENDING_REVIEW: Payment in process of validation.
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>
Last modified June 24, 2022: clon issue (d73e43fe)