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:
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.
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.
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's
id, 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
Response
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= [email protected]" \
-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":"[email protected] 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.
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's
idwhich 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>
Payment form
Payment form
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
Response sample
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":"[email protected]",
"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":"[email protected] 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
Example Capture (CP) Request
Response
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": "[email protected] 08:36:44 +0000",
"timestamp": "2019-05-08 23:14:09+0000",
"ndc": "8a8294174e918ca6014e9c6f5ae12a9c_f9b9ee0131494621a93d186cbf8cca03"
}
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.
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's
id, 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
Response
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= [email protected]" \
-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":"[email protected] 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
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's
idwhich 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>
Payment form
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
Response sample
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":"[email protected]",
"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":"[email protected] 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
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.
Last modified 3yr ago