documentation
  • LATAM Payment Methods
  • Integration guide
    • Getting started
      • Payment Methods
      • Payment Types
      • Supported Brands
      • Overview (Authentication and Endpoint)
    • COPYandPAY
      • Customization
      • Advanced Options
      • COPYandPAY API
      • Tokenization
      • Mobile Optimization
    • Server-to-Server
      • Tokenization
  • Manage Payments
    • Backoffice Operations
    • Recurring Payments
    • Installments
    • ZeroAuth
    • Transactions status
  • Instant Payment Notification (IPN) / Webhooks
    • General Information
    • Integration Guide
  • Queries
    • XML Integrator (Queries)
  • Reporting
    • Overview
    • Processed Report
    • Payout Report
    • Report Availability
    • Glossary of Fields
  • Compliance
    • Mandatory parameters by country
    • Test cards by country
    • Customer Identification Number by country (Customer ID)
    • Supported Countries and States
    • Requirements Before Going-Live
  • Reference
    • API Reference
    • Result Codes
  • FAQ
    • COPYandPAY FAQ
    • PCI DSS
    • TLS 1.2
Powered by GitBook
On this page
  • Sending the initial Payment
  • Quick links
  • COPYandPAY - INITIAL
  • Server-to-Server - INITIAL
  • Sending a repeated Payment
  • COPYandPAY - REPEATED
  • Server-to-Server - REPEATED
  1. Manage Payments

Recurring Payments

PreviousBackoffice OperationsNextInstallments

Last updated 1 year ago

You can perform recurring payments by just adding one additional parameter, recurringType, to the payment request.

A recurring workflow consists of two phases:

  1. without a cvv using a token previously stored during the initial payment.

Sending the initial Payment

During the initial payment, marked by the parameter recurringType with the value INITIAL, the customer is present. Therefore, this initial request should contain additional parameters that authenticate the customer like card.cvv for card payments.

Quick links

  • COPYandPAY

  • Server-to-Server

COPYandPAY - INITIAL

In COPYandPAY you get this behaviour out of the box, so all you have to do is to follow the COPYandPAY Integration guide and add the following parameter to the /v1/checkouts request in :

recurringType=INITIAL
createRegistration=true (to create a registrationid for future repeated payments).
curl https://test.oppwa.com/v1/checkouts \
 -d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
 -d "amount=1.00" \
 -d "currency=BRL" \
 -d "paymentType=DB" \
 -d "merchantTransactionId=Order Number 123" \
 -d "customer.merchantCustomerId=12345678909" \
 -d "customer.givenName=Jose" \
 -d "customer.surname=da Silva" \
 -d "customer.email= info@provider.com" \
 -d "customer.ip=123.123.123.123" \
 -d "descriptor=123 Usage" \
 -d "billing.city=Sao Paulo" \
 -d "billing.country=BR" \
 -d "billing.state=SP" \
 -d "billing.street1=Rua Itapeva 547" \
 -d "billing.postcode=01332000" \
 -d "customParameters[product]=1 month membership" \
 -d "customParameters[merchant_website]=www.store.com" \
 -d "recurringType=INITIAL" \
 -d "testMode=EXTERNAL" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
"result":{
"code":"000.200.100",
"description":"successfully created checkout"
},
"buildNumber":"4ce5e2dcbc57295c15e35c9936b1d7a5c41f6655@2016-05-25 13:28:08 +0000",
"timestamp":"2016-06-02 23:41:28+0000",
"id":"5D6AE9181EB6E8899F2AF0B3F9796249.sbg-vm-tx01"
}
<form action="{shopperResultUrl}" class="paymentWidgets"> VISA MASTER AMEX DINERS DISCOVER ELO JCB</form>
curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="

Response:

{
  "id":"8a8294495507351b0155137ed0fd7fc4",
  "registrationId":"8a82944a5507355f0155137ecf1209ff",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"1.00",
  "currency":"BRL",
  "descriptor":"123 Usage",
  "merchantTransactionId":"Order Number 123",
  "recurringType":"INITIAL",
  "result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
    "card":{
    "bin":"411111",
    "last4Digits":"1111",
    "holder":"Jose da Silva",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "customer":{
    "givenName":"Jose",
    "surname":"da Silva",
    "merchantCustomerId":"12345678909",
    "email":"info@provider.com",
    "ip":"123.123.123.123"
  },
  "billing":{
    "street1":"Rua Itapeva 547",
    "city":"Sao Paulo",
    "state":"SP",
    "postcode":"01332000",
    "country":"BR"
  },
  "customParameters":{
    "product":"1 month membership",
    "merchant_website":"www.store.com"
  },
  "risk":{
    "score":"100"
  },
  "buildNumber":"4ce5e2dcbc57295c15e35c9936b1d7a5c41f6655@2016-05-25 13:28:08 +0000",
  "timestamp":"2016-06-02 23:42:09+0000",
}

Using the server-to-server integration, you have the option to append the parameter recurringTypeto the initial /v1/payments request which also stores the card data:

Server-to-Server - INITIAL

Using the server-to-server integration, you have the option to append the parameter recurringTypeto the initial /v1/payments request which also stores the card data:

recurringType=INITIAL
createRegistration=true (to create a registrationid for future repeated payments).

For some cases you might want to use an alternative approach: If the shopper just registered his data without sending a payment at the same time, you would have sent his payment directly to the /v1/registrations endpoint as described here. In the same way as described above, the recurringType=INITIAL parameter can be added to the request to indicate that this is the first in a series of recurring payments.

curl https://test.oppwa.com/v1/payments \
 -d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
 -d "merchantTransactionId=Order Number 123" \
 -d "customer.merchantCustomerId=12345678909" \
 -d "amount=1.00" \
 -d "currency=BRL" \
 -d "paymentType=DB" \
 -d "paymentBrand=VISA" \
 -d "card.number=4111111111111111" \
 -d "card.holder=Jose da Silva" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2028" \
 -d "card.cvv=123" \
 -d "customer.givenName=Jose" \
 -d "customer.surname=da Silva" \
 -d "customer.email= info@provider.com" \
 -d "customer.ip=123.123.123.123" \
 -d "descriptor=123 Usage" \
 -d "billing.city=Sao Paulo" \
 -d "billing.country=BR" \
 -d "billing.state=SP" \
 -d "billing.street1=Rua Itapeva 547" \
 -d "billing.postcode=01332000" \
 -d "customParameters[product]=1 month membership" \
 -d "customParameters[merchant_website]=www.store.com" \
 -d "recurringType=INITIAL" \
 -d "testMode=EXTERNAL" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "id":"8ac7a4a06a585554016a5ac4134739ca",
  "registrationId":"8ac7a4a16a585296016a5ac4108a2bbf",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"1.00",
  "currency":"BRL",
  "descriptor":"123 Usage",
  "merchantTransactionId":"Order Number 123",
  "result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
    "card":{
    "bin":"411111",
    "last4Digits":"1111",
    "holder":"Jose da Silva",
    "expiryMonth":"05",
    "expiryYear":"2028"
  },
  "customer":{
    "givenName":"Jose",
    "surname":"da Silva",
    "merchantCustomerId":"12345678909",
    "email":" info@provider.com",
    "ip":"123.123.123.123"
  },
  "billing":{
    "street1":"Rua Itapeva 547",
    "city":"Sao Paulo",
    "state":"SP",
    "postcode":"01332000",
    "country":"BR"
  },
  "customParameters":{
    "merchant_website":"www.store.com",
    "product":"1 month membership",
    "OPP_card.bin":"411111"
  },
  "resultDetails":{
  "acquirerTxId9":"TEST_NTR_CODE",
  },

  "risk":{
    "score":"0"
  },
  "buildNumber":"aec07372955d4d6a9e4a6cb946b52ff339acb83d@2019-04-23 08:51:22 +0000",
  "timestamp":"2019-04-26 17:49:21+0000",
  "ndc":"8a8294174e918ca6014e9c6f5ae12a9c_16d4adfc8c1b4494b7dedc6d6a262f70"
}Sending a repeated Payment

In the response of the initial transactions, the field “acquirerTxId9” will bring a parameter provided by the card scheme, to be used in the subsequent transactions using this card

Sending a repeated Payment

Any payment request following the initial one must have the parameter recurringType with the value REPEATED. This flag not only indicates that the request is part of a series of payments on this account, but also tells the payment system that no user is present and therefore the parameter card.cvv is not part of the request. This fact in combination with the stored payment data of the registration greatly reduces the number of parameters of such a request:

recurringType=REPEATED

COPYandPAY - REPEATED

curl https://test.oppwa.com/v1/registrations/{id}/payments \
 -d "entityId=8a8294174e918ca6014e9c73d69c2ab3" \
 -d "amount=1.00" \
 -d "currency=BRL" \
 -d "paymentType=DB" \
 -d "customer.merchantCustomerId=12345678909" \
 -d "testMode=EXTERNAL" \
 -d "recurringType=REPEATED" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "id":"8ac7a49f6a585294016a5ae124bb5624",
  "paymentType":"DB",
  "amount":"1.00",
  "currency":"BRL",
  "descriptor":"",
  "result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
    "customer":{
    "merchantCustomerId":"12345678909"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"aec07372955d4d6a9e4a6cb946b52ff339acb83d@2019-04-23 08:51:22 +0000",
  "timestamp":"2019-04-26 18:21:17+0000",
  "ndc":"8a8294174e918ca6014e9c73d69c2ab3_6864a3cd063447648091a05f44e35811"
}

Server-to-Server - REPEATED

To send the request of a repeated transaction, the field “customParameters[NTR]” must be filled with the information received previously in the initial one, in the field “acquirerTxid9", so the issuers can recognize the recurrency chain of the transaction

curl https://test.oppwa.com/v1/registrations/{id}/payments \
 -d "entityId=8a8294174e918ca6014e9c73d69c2ab3" \
 -d "merchantTransactionId=Order Number 123" \
 -d "customer.merchantCustomerId=12345678909" \
 -d "amount=21.00" \
 -d "currency=BRL" \
 -d "customParameters[NTR]=TEST_NTR_CODE"
 -d "paymentType=DB" \
 -d "recurringType=REPEATED" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "id":"8ac7a4a06a585554016a5ae9905b5c4d",
  "paymentType":"DB",
  "amount":"21.00",
  "currency":"BRL",
  "descriptor":"",
  "merchantTransactionId":"Order Number 123",
  "result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "customer":{
    "merchantCustomerId":"12345678909"
  },
  "resultDetails":{
  "acquirerTxId9":"TEST_NTR_CODE",
  },

  "risk":{
    "score":"0"
  },
  "buildNumber":"aec07372955d4d6a9e4a6cb946b52ff339acb83d@2019-04-23 08:51:22 +0000",
  "timestamp":"2019-04-26 18:30:18+0000",
  "ndc":"8a8294174e918ca6014e9c73d69c2ab3_37eff6eeff5a40d7b7fb86ffdeba564c"
}
The initial payment request.
Subsequent payment requests
recurringType=INITIAL
recurringType=REPEATED
recurringType=INITIAL
recurringType=REPEATED
step 1