COPYandPAY

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.

1 - Prepare the checkout

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

2 - Create the payment form

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

3 - Get the payment status

Find out if the payment was successful.

Card Payment (CC)

• Preauthorization (PA) + Capture (CP)

• Debit (DB)

Preauthorization (PA) + Capture (CP)

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 backoffice operations for more details.

1. Prepare the checkout

First, perform a Server-to-Server POST request to prepare the checkout with the required data, including the order type, amount, currency, and the mandatory parameters. 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 API Reference

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

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

Example Preauthorization (PA) Request

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= [e-mail]" \
 -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=="

Response

{
  "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"
}

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

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>

View the customization guide for more information on customizing the payment form.

View the customization guide for more information on customizing the payment 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

Request sample

curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294174d2e4980014d340322fa09a7" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="

Response sample

{
  "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":"[e-mail]",
    "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)

Example Capture (CP) Request

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=="

Response

{
	"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

First, perform a Server-to-Server POST request to prepare the checkout with the required data, including the order type, amount, currency and the mandatory parameters. 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.

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

Example Debit (DB) Request

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= [e-mail]" \
 -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=="

Response

{
  "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"
}

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

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>

View the customization guide for more information on customizing the payment 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

Request sample

curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294174d2e4980014d340322fa09a7" \
 -H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="

Response sample

{
  "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":"[e-mail]",
    "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

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 backoffice operations guide.