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
  • How it works:
  • Card Payment (CC)
  • Preauthorization (PA) + Capture (CP)
  • 1. Prepare the checkout
  • 2. Create the payment form
  • 3. Get the payment status
  • Capture (CP)
  • Debit (DB)
  • 1. Prepare the checkout
  • 2. Create the payment form
  • 3. Get the payment status
  • Backoffice operations
  1. Integration guide

COPYandPAY

PreviousOverview (Authentication and Endpoint)NextCustomization

Last updated 5 years ago

COPYandPAY is a PCI-DSS compliant payment-form solution, making it both secure and simple-to-integrate. There are just three simple steps required to integrate the card payment method:

How it works:

Forms are used to collect user information with different element types of input, select, checkboxes, radios buttons and more.

Send the request parameters Server-to-Server to prepare the payment form.

Display the payment form on your checkout page, the shopper submits the payment data.

Find out if the payment was successful.

Card Payment (CC)

Preauthorization (PA) + Capture (CP)

1. Prepare the checkout

Please note that for a HTTP POST request all the parameters are expected to go into the message body and not into the URL.

curl https://test.oppwa.com/v1/checkouts \
 -d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
 -d "amount=1.00" \
 -d "currency=BRL" \
 -d "paymentType=PA" \
 -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" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "result":{
    "code":"000.200.100",
    "description":"successfully created checkout"
  },
  "buildNumber":"e61441a649f53ee436210a78b3c5a713f3e54e8a@2019-05-08 08:36:44 +0000",
  "timestamp":"2019-05-09 00:10:29+0000",
  "ndc":"8FB85764DDCAB4CB15E8B8DDB9B3A3C3.uat01-vm-tx04",
  "id":"8FB85764DDCAB4CB15E8B8DDB9B3A3C3.uat01-vm-tx04"
}

2. Create the payment form

To create the payment form, you just need to add the following lines of HTML/JavaScript to your page and populate the following variables:

The checkout'sidwhich you received in the response from step 1.

<script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>

The shopperResultUrl, is the page on your site where the customer should be redirected to after the payment is processed as well as the brands that shall be available for this payment.

<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>

3. Get the payment status

Once the payment has been processed, the customer is redirected to your shopperResultUrlalong with a GET parameter resourcePath.

Important: The baseUrl must end in a "/", e.g. "https://test.oppwa.com/".

Then, to get the status of the payment, you do a GET request to the baseUrl + resourcePath, including your authentication parameters.

Example of a resourcePath:

resourcePath=/v1/checkouts/{checkoutId}/payment
curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294174d2e4980014d340322fa09a7" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "id":"8ac7a49f6a8bd5d4016a8e6c84382b7b",
  "paymentType":"PA",
  "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":"465382",
    "last4Digits":"8551",
    "holder":"Transaction sample",
    "expiryMonth":"06",
    "expiryYear":"2020"
  },
  "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":{
    "SHOPPER_EndToEndIdentity":"9eba4556522f5d6e6a99b26951a1740699acc60c46f863eb606293eeede23d61",
    "product":"1 month membership",
    "CTPE_DESCRIPTOR_TEMPLATE":"${USAGE}",
    "merchant_website":"www.store.com"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
  "timestamp":"2019-05-06 18:33:58+0000",
  "ndc":"5B7DEA439C54F05AEA809ECA1E5C3D66.uat01-vm-tx01"
}

Important: A throttling rule applies for get payment status calls. Per checkout, it is allowed to send two get payment requests in a minute.

We recommend that you verify the following fields from the Payment Status response by comparing the returned values with expected:

  • ID(s)

  • Amount

  • Currency

  • Brand

  • Type

Capture (CP)

curl https://test.oppwa.com/v1/payments/8ac7a49f6a8bd5d4016a8e6c84382b7b \
 -d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
 -d "amount=1.00" \
 -d "currency=BRL" \
 -d "paymentType=CP" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
	"id": "8ac7a4a26a977d95016a99b9c15b00c8",
	"referencedId": "8ac7a49f6a8bd5d4016a8e6c84382b7b",
	"paymentType": "CP",
	"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'"
	},
	
	"customer": {
		"merchantCustomerId": "12345678909"
	},
	"buildNumber": "e61441a649f53ee436210a78b3c5a713f3e54e8a@2019-05-08 08:36:44 +0000",
	"timestamp": "2019-05-08 23:14:09+0000",
	"ndc": "8a8294174e918ca6014e9c6f5ae12a9c_f9b9ee0131494621a93d186cbf8cca03"
}

Debit (DB)

A DB is created by sending a POST request over HTTPS to the /v1/checkouts resource. The request should include all required information such as your authentication credentials, the type of transaction, the amount and the payment information such as card details. A DB request effectively combines a PA and capture (CP) request, automatically requesting that the funds are cleared if the authorization was successful.

1. Prepare the checkout

Please note that for a HTTP POST request all the parameters are expected to go into the message body and not into the URL.

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" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "result":{
    "code":"000.200.100",
    "description":"successfully created checkout"
  },
  "buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
  "timestamp":"2019-05-06 18:32:22+0000",
  "ndc":"5B7DEA439C54F05AEA809ECA1E5C3D66.uat01-vm-tx01",
  "id":"5B7DEA439C54F05AEA809ECA1E5C3D66.uat01-vm-tx01"
}

2. Create the payment form

To create the payment form you just need to add the following lines of HTML/JavaScript to your page and populate the following variables

The checkout'sidwhich you received in the response from step 1.

<script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>

The shopperResultUrl, is the page on your site where the customer should be redirected to after the payment is processed as well as the brands which shall be available for this payment.

<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>

3. Get the payment status

Once the payment has been processed, the customer is redirected to your shopperResultUrlalong with a GET parameter resourcePath.

Important: The baseUrl must end in a "/", e.g. "https://test.oppwa.com/".

Then, to get the status of the payment, you do a GET request to the baseUrl + resourcePath, including your authentication parameters.

Example of a resourcePath:

resourcePath=/v1/checkouts/{checkoutId}/payment
curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294174d2e4980014d340322fa09a7" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
{
  "id":"8ac7a49f6a8bd5d4016a8e6c84382b7b",
  "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":"465382",
    "last4Digits":"8551",
    "holder":"Transaction sample",
    "expiryMonth":"06",
    "expiryYear":"2020"
  },
  "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":{
    "SHOPPER_EndToEndIdentity":"9eba4556522f5d6e6a99b26951a1740699acc60c46f863eb606293eeede23d61",
    "product":"1 month membership",
    "CTPE_DESCRIPTOR_TEMPLATE":"${USAGE}",
    "merchant_website":"www.store.com"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
  "timestamp":"2019-05-06 18:33:58+0000",
  "ndc":"5B7DEA439C54F05AEA809ECA1E5C3D66.uat01-vm-tx01"
}

Important: A throttling rule applies for get payment status calls. Per checkout, it is allowed to send two get payment requests in a minute.

We recommend that you verify the following fields from the Payment Status response, by comparing the returned values with expected:

  • ID(s)

  • Amount

  • Currency

  • Brand

  • Type

Backoffice operations

A PA is created by sending a POST request over HTTPS to the /v1/checkouts resource. The request should include all required information such as your authentication credentials, the type of transaction, the amount, and the payment information such as card details. A capture may be sent against a successful PA to request the funds being sent for clearing. See for more details.

First, perform a Server-to-Server POST request to prepare the checkout with the required data, including the order type, amount, currency, and the . The response to a successful request is a JSON string containing a checkout'sid, which is required in the second step to create the payment form.

For a full list of parameters which can be sent in the prepare checkout request, please see the

For a full list of parameters which can be sent in the prepare checkout request, please see the

For a full list of parameters which can be sent in the prepare checkout request, please see the .

View the for more information on customizing the payment form.

View the for more information on customizing the payment form.

First, perform a Server-to-Server POST request to prepare the checkout with the required data, including the order type, amount, currency and the . The response to a successful request is a JSON string containing a checkout'sid, which is required in the second step to create the payment form.

For a full list of parameters which can be sent in the prepare checkout request, please see the

View the for more information on customizing the payment form.

COPYandPAY is used to securely accept the payment data. Once the payment data has been processed you can perform refunds or other backoffice operations by following our .

mandatory parameters
API Reference
API Reference
API Reference
customization guide
customization guide
mandatory parameters
API Reference
customization guide
backoffice operations guide
1 - Prepare the checkout
2 - Create the payment form
3 - Get the payment status
Preauthorization (PA) + Capture (CP)
Debit (DB)
Payment form
Payment form
Payment form
backoffice operations