COPYandPAY Integration Guide

COPYandPAY is a SAQ-A compliant payment-form solution, making it both secure and simple-to-integrate.

There are just three simple steps required to integrate :

How it works

Prepare the checkout

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

Create the payment form(s)

Display the payment form on your checkout page and the shopper submits the payment information.

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 and currency. The response to a successful request is a JSON string with an id, which is required in the second step to create the payment form.

For a full list of parameters that 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.

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 populating the following variables

The checkout's id that you got in the response from step 1,
The shopperResultUrl, which is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available.

<html>
<head>
<style>
   .cnpBillingCheckoutWrapper {position:relative;}
   .cnpBillingCheckoutHeader {width:100%;border-bottom: 1px solid #c0c0c0;margin-bottom:10px;}
   .cnpBillingCheckoutLeft {width:240px;margin-left: 5px;margin-bottom: 10px;border: 1px solid #c0c0c0;display:inline-block;vertical-align: top;padding:10px;}
   .cnpBillingCheckoutRight {width:50%;margin-left: 5px;border: 1px solid #c0c0c0;display:inline-block;vertical-align: top;padding:10px;}
   .cnpBillingCheckoutOrange {font-size:110%;color: rgb(255, 60, 22);font-weight:bold;}
   div.wpwl-wrapper, div.wpwl-label, div.wpwl-sup-wrapper { width: 100% }
   div.wpwl-group-expiry, div.wpwl-group-brand { width: 30%; float:left }
   div.wpwl-group-cvv { width: 68%; float:left; margin-left:2% }
   div.wpwl-group-cardHolder, div.wpwl-sup-wrapper-street1, div.wpwl-group-expiry { clear:both }
   div.wpwl-sup-wrapper-street1 { padding-top: 1px }
   div.wpwl-wrapper-brand { width: auto }
   div.wpwl-sup-wrapper-state, div.wpwl-sup-wrapper-city { width:32%;float:left;margin-right:2% }
   div.wpwl-sup-wrapper-postcode { width:32%;float:left }
   div.wpwl-sup-wrapper-country { width: 66% }
   div.wpwl-wrapper-brand, div.wpwl-label-brand, div.wpwl-brand { display: none;}
   div.wpwl-group-cardNumber { width:70%; float:left; font-size: 20px; }
   div.wpwl-group-brand { width:30%; float:left; margin-top:28px }
   div.wpwl-brand-card { width: 60px }
   div.wpwl-brand-custom { margin: 0px auto; background-image: url("https://oppwa.com/v1/paymentWidgets/img/brand.png") }
</style>
<script src="https://code.jquery.com/jquery.js" type="text/javascript"></script> 
<script type="text/javascript"> 
   var wpwlOptions = {
     style: "plain",
     billingAddress: {
       country: "US",
       state: "NY",
       city: "New York",
       street1: "111 6th Avenu",
       street2: "",
       postcode: "12312"
     },
     forceCardHolderEqualsBillingName: true,
     showCVVHint: true,
     brandDetection: true,
     onReady: function(){ 
       $(".wpwl-group-cardNumber").after($(".wpwl-group-brand").detach());
       $(".wpwl-group-cvv").after( $(".wpwl-group-cardHolder").detach());
       var visa = $(".wpwl-brand:first").clone().removeAttr("class").attr("class", "wpwl-brand-card wpwl-brand-custom wpwl-brand-VISA")
       var master = $(visa).clone().removeClass("wpwl-brand-VISA").addClass("wpwl-brand-MASTER");
       $(".wpwl-brand:first").after( $(master)).after( $(visa));
     },
     onChangeBrand: function(e){
       $(".wpwl-brand-custom").css("opacity", "0.3");
       $(".wpwl-brand-" + e).css("opacity", "1"); 
     }
   }
</script>
  <script src="https://test.cdn.alipay-seller.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
</head>
<body>
<div class="cnpBillingCheckoutWrapper">
  <div class="cnpBillingCheckoutHeader"><img src="https://alipay-seller.alipay-seller.docs.oppwa.com/sites/default/files/poweredByAlipay.png" /></div>
  <div class="cnpBillingCheckoutLeft">
    <div class="panel panel-default">
    <div class="panel-heading">
      <h3 class="panel-title cnpBillingCheckoutPanelTitle">Order total: US 99.00</h3>
    </div>
    <div class="panel-body">
      <p><strong>Order info</strong></p>
      <p><strong>Order NO: 30038818375462</strong><br />
      Keter Rattan Cool Barh AliExpress AliExpress KR..</p>
      <p style="text-align:right"><strong>US $95.00</strong></p>
      <p><strong>Order NO: 30038818375462</strong><br />
      Keter Rattan Cool Barh AliExpress..</p>
      <p style="text-align:right"><strong>US $4.99</strong></p>
    </div>
    <hr />
    <div class="panel-body">
      <img src="https://alipay-seller.alipay-seller.docs.oppwa.com/sites/default/files/schemeLogos.png" />
    </div>
    </div>
  </div>
  <div class="cnpBillingCheckoutRight">
    <p>Payment Total: <span class="cnpBillingCheckoutOrange">US $99.00</span></p>
    <hr />
  <form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX">
</form>
  </div>
</div>
</body>
</html>

View the customization guide for more information on customizing the payment form. Please note if you are using SAQ-A compliant credit card form click Enter button on your keyboard to execute the payment.

Display of multiple card forms is now supported. This feature can be used by merchants for card brand promotion and allows the merchant to group card brands across multiple forms as per the need. To put this feature at work, add any number of <form> tag elements as above. The data-brands attribute of the rendered card forms can be configured as per the merchant need.
```
<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA"></form>
```
```
<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="AMEX MASTER DISCOVER CARTEBANCAIRE"></form>
```

Show all supported brands

Brand	Async / sync workflow

A checkout id expires when a payment has been finalized successfully by user, but not later than 30 minutes. Before it expires, it can be used multiple times in order to retrieve a valid payment form. This can occur for example when a user does not finish a payment and reloads the page, or uses the back button of the browser. Therefore you don't have to generate a new checkout ID in such scenarios. However be aware that such cases can generate multiple transactions in the system, for example one (or more) failed and another one successful, based on the same checkout id.

3. Get the payment status

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

Important: The baseUrl must end in a "/", e.g. "https://test.cdn.alipay-seller.com/".

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

Example of a resourcePath:

resourcePath=/v1/checkouts/{checkoutId}/payment

Once a status response is successful the checkout identifier can't be used anymore. In this case the Transaction Reports endpoint can be used to get the transaction status using the payment id.

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.