Learn the payment flow for a subscription payments integration where the customer pays the initial payment with the iframe checkout and then you collect recurring payments at regular intervals until the subscription is cancelled.

📘
Merchant transaction ID
We recommend that you use a merchant transaction ID format to associate all the subscription payments. For example, you could use an identifier with a suffix to distinguish each payment.

1. Create the checkout in the payment gateway

The first step is to perform a POST request to the payment gateway to create a checkout, with the payment type, amount, currency, and required attributes.

Here is an example request to create a checkout for the initial payment of a subscription order.

curl https://eu-test.oppwa.com/v1/checkouts \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
-d "entityId={channelId}" \
-d "amount=20.00" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "integrity=true" \
-d "merchantTransactionId=P126" \
-d "billing.street1=Ave. Diagonal 611" \
-d "billing.city=Barcelona" \
-d "billing.country=ES" \
-d "billing.postcode=08028" \
-d "standingInstruction.type=RECURRING" \
-d "standingInstruction.mode=INITIAL" \
-d "standingInstruction.source=CIT" \
-d "standingInstruction.expiry=9999-12-31" \
-d "standingInstruction.frequency=0001" \
-d "standingInstruction.recurringType=SUBSCRIPTION" \
-d "createRegistration=true" \
-d "customer.email=js@example.com" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
-d "customer.givenName=Josep" \
-d "customer.surname=Sarda" \
-d "customer.phone=34667666666" \
-d "customer.merchantCustomerId=CUST04" \
-d "threeDSecure.challengeIndicator=04" \
-d "customParameters[StoreCredentialType]=CIT" \
-d "customParameters[CRMCustomerID]=CRM CUST01" \
-d "customParameters[SubscriptionID]=S-00100" \
-d "customParameters[PaymentType]=Subscription" \ 
-d "customParameters[3DS2_enrolled]=true" \
-d "customParameters[3DS2_flow]=challenge" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer {auth_token}"

Replace the example values with your values and replace the {channelId} and {auth_token} with your API credentials.

Here are some notes about the parameters in this request

Parameters	Notes
paymentType	Can be `DB` ("debit") or `PA` ("preauthorization"). For `PA`, use the back-office API to capture the payment.
merchantTransactionId	We recommend that you provide a unique identifier for each transaction.
billing address	The billing address is required if you use 3DS verification; otherwise, it is recommended.
standingInstruction.type	Set to `RECURRING`to specify an order with recurring payments.
standingInstruction.mode	Set to `INITIAL`to specify the first payment where you are saving a card
standingInstruction.source	Set to `CIT`to specify a customer-initiated transaction.
standingInstruction.expiry	Set to `9999-12-31`to create a subscription order that is valid until cancelled.
standingInstruction.frequency	Set to `0001`to create a subscription order.
standingInstruction.recurringType	Set to `SUBSCRIPTION`.
createRegistration	Set to `true`to save the customer's card for future payments.
customer details	We recommend you supply customer details, including a unique identifier for each customer.
threeDSecure.challengeIndicator	The recommended value is `04`. This means that 3DS is mandated in your region, and it tells the issuer to define the challenge type.
customParameters	We recommend that you add custom parameters to uniquely identify the transaction initiation type, customer, order, and purchase type. The custom data you send in these parameters will be returned in the payment response. You can use these parameters to pair and match information from the payment gateway with your business systems. You can create an unlimited number of unique and properly-named custom parameters.

When you are testing your integration, you can use the following parameters.

Parameters	Notes
customParameters[3DS2_enrolled][3DS2_enrolled]	This parameter is for the test environment only. Set to `true` for any card to specify that the card is enrolled in 3DS. Or, instead of the 3DS test parameters, you can use 3DS test cards.
customParameters[3DS2_flow][3DS2_flow]	This parameter is for the test environment only. Set to `challenge` to force a 3DS challenge, or `frictionless`. Or, instead of the 3DS test parameters, you can use 3DS test cards.
testMode	This parameter is for the test environment only. Set to `EXTERNAL` to send the transaction to the acquirer's test environment. Set to `INTERNAL` to process the transaction in the gateway only.

For more details on 3DS testing, see the Gateway 3DS testing guide.

For full details of all the parameters, see Checkout request attributes.

Test in the gateway playground

To test the initial subscription request in the gateway playground, use the checkout creation endpoint for this request: Gateway documentation for iframe widget integration. Here is some sample data.

entityId={channelId}
amount=20.03
currency=EUR
paymentType=DB
integrity=true
merchantTransactionId=P126
billing.street1=Calle Principal 123
billing.city=Barcelona
billing.country=ES
billing.postcode=08028
standingInstruction.type=RECURRING
standingInstruction.mode=INITIAL
standingInstruction.source=CIT
standingInstruction.expiry=9999-12-31
standingInstruction.frequency=0001
standingInstruction.recurringType=SUBSCRIPTION
createRegistration=true
customer.email=js@example.com
customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af
customer.givenName=John
customer.surname=Smith
customer.phone=34667666666
customer.merchantCustomerId=CUST01
threeDSecure.challengeIndicator=04
customParameters[StoreCredentialType]=CIT
customParameters[CRMCustomerID]=CRM CUST01
customParameters[SubscriptionID]=S-00100
customParameters[PaymentType]=Subscription
customParameters[3DS_enrolled]=true
customParameters[3DS2_flow]=challenge
testMode=EXTERNAL

Example response

Your successful request will receive a JSON response. Here is an example of this response.

{
  "result":{
    "code":"000.200.100",
    "description":"successfully created checkout"
  },
  "buildNumber":"d7f3057c29b9a26d5151336767387bb393720d7e@2024-10-14 09:16:49 +0000",
  "timestamp":"2024-10-15 14:58:46+0000",
  "ndc":"702B930F656317E0D29A22D195F75A59.uat01-vm-tx03",
  "id":"702B930F656317E0D29A22D195F75A59.uat01-vm-tx03",
  "integrity":"sha384-KnYRC1jbE3C9SMGbJ5eU2Gx+AM9PCaApfqS6lk8MpPlvk9jIii4PFu297dPu4wcy"
}

From this response, you will need the value of the id and integrity for the next step.

2. Create the payment form on your web page

To create the payment form on your web page, add the following lines of JavaScript and HTML and enter the following variables.

This script gets the checkout from the payment gateway. Replace the {checkoutId} with the value of the id and replace {integrity} with the value of integrity from the response in Step 1. Replace anonymous with the address of your website that loads the COPYandPAY checkout.

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

This HTML displays the checkout. The shopperResultUrl is a page on your site where the customer should be redirected after the payment is processed.

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

For example, a checkout script could look like this.

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId=702B930F656317E0D29A22D195F75A59.uat01-vm-tx03"
        integrity="sha384-KnYRC1jbE3C9SMGbJ5eU2Gx+AM9PCaApfqS6lk8MpPlvk9jIii4PFu297dPu4wcy"
        crossorigin="https://example.com">
</script>

For example, your checkout HTML could look as follows.

<form action="https://myshop.example.com/paid" class="paymentWidgets" data-brands="VISA MASTER"></form>

You can use the same checkout ID multiple times to retrieve a valid payment form. The checkout expires in 30 minutes, and after it expires, you must renew the checkout. Send a new request to create a checkout and use the new checkoutId to create the payment form again.

👍
Customise the payment widget
To customise the payment widget to match the look of your own site, see this customisation guide and the advanced options guide.
You can also add extra fields to this form, for example, to obtain the customer details during checkout.
To display some sample customisations, go to demo checkouts. You can obtain the code for the demo checkouts at Demo checkouts on GitHub.

Here is an example of a customised iframe for subscription payments.

3. Get payment status from the checkout in the gateway

When the payment has been processed, CardCorp will redirect the customer to your shopperResultUrl.

To get the payment status, make a GET request to the payment link of your checkout in the gateway, as follows.

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

Replace the {id}and the {auth_token} with your values.

Here is an example of the result of a successful payment.

{
  "id":"8ac7a4a1913510db0191363e7df14d83",
  "registrationId":"8ac7a4a0913518ad0191363e7cb02899",
  "processingEntityId":{channelId},
  "paymentType":"DB",
  "paymentBrand":"MASTER",
  "amount":"18.00",
  "currency":"EUR",
  "descriptor":"3930.3187.7663 ECOMChannel",
  "merchantTransactionId":"P155",
  "recurringType":"INITIAL",
  "result":{
    "cvvResponse":"U",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails":{
    "ExtendedDescription":"Approved",
    "usedChallengeIndicator":"04",
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "ConnectorTxID1":"869689||true|UMCC634237   ||0809|710| ||RECURRING|80||false|false|true|812|1",
    "connectorId":"422208869689",
    "ConnectorTxID3":"422208869689|00|||1||0809082557|||||||||||||Berlin|",
    "ConnectorTxID2":"949375||8ac7a0b39134af7f0191363e9a26060c",
    "AcquirerResponse":"00",
    "reconciliationId":"3930.3187.7663",
    "CardholderInitiatedTransactionID":"MCC6342370809",
    "SchemeResponseCode":"00"
  },
  "card":{
    "bin":"520000",
    "binCountry":"MY",
    "last4Digits":"0049",
    "holder":"John Smith",
    "expiryMonth":"05",
    "expiryYear":"2027",
    "issuer":{
      "bank":"PUBLIC BANK BERHAD",
      "website":"HTTPS://WWW.PBEBANK.COM/",
      "phone":"1-800-22-5555"
    },
    "type":"CREDIT",
    "level":"STANDARD",
    "country":"MY",
    "maxPanLength":"16",
    "binType":"PERSONAL",
    "regulatedFlag":"N"
  },
  "customer":{
    "givenName":"John",
    "surname":"Smith",
    "merchantCustomerId":"CUST01",
    "phone":"34667666666",
    "email":"js@example.com",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af"
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08028",
    "country":"ES"
  },
  "threeDSecure":{
    "eci":"02",
    "version":"2.2.0",
    "dsTransactionId":"c2882536-9d0c-470d-9f27-7f31ae12dedf",
    "challengeMandatedIndicator":"N",
    "transactionStatusReason":"17",
    "acsTransactionId":"a81a07a0-1e37-4012-ad1e-f22675653832",
    "cardHolderInfo":"",
    "authType":"01",
    "flow":"challenge",
    "authenticationTimestamp":"202408090825",
    "authenticationStatus":"Y"
  },
  "customParameters":{
    "StandingInstructionAPI":"true",
    "3DS_enrolled":"true",
    "SHOPPER_EndToEndIdentity":"834ea053afb4d42590b6ec5e9eaf07fa7f954495cc0245797eebcf430e43d6c6",
    "SubscriptionID":"S-00100",
    "CTPE_DESCRIPTOR_TEMPLATE":"",
    "StoredCredentialType":"CIT",
    "PaymentType":"Subscription",
    "CRMCustomerID":"CRM CUST01",
    "3DS2_flow":"challenge",
    "StoreCredentialType":"CIT"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"174903ec91870d5654938dd40f55da3b35036b23@2024-08-08 12:50:27 +0000",
  "timestamp":"2024-08-09 08:25:57+0000",
  "ndc":"982A26D3C1A540688241F8B69D23E336.uat01-vm-tx02",
  "standingInstruction":{
    "source":"CIT",
    "type":"RECURRING",
    "mode":"INITIAL",
    "initialTransactionId":"MCC6342370809",
    "expiry":"9999-12-31",
    "frequency":"0001",
    "recurringType":"SUBSCRIPTION"
  },
  "source":"OPPUI",
  "paymentMethod":"CC",
  "shortId":"3930.3187.7663"
}

To interpret the payment response, see Transaction results.

To collect a repeated payment for a subscription order, you will need the card registrationId and the CardholderInitiatedTransactionID from the payment result.

There is a request limit for payment status calls, after which, the gateway will reduce your access to the endpoint with throttling. You can send two (2) GET payment requests per minute for each checkout ID.

When you get the payment response status, compare the returned values with the expected values for the following fields: ID(s), amount, currency, brand, type.

After a payment response status is successful, you cannot use the checkout identifier again. So if you need to get the status, use the Transaction Reports endpoint with the payment id. You will also need the id to manage the payment with the Backoffice API. See Backoffice API operations.

4. Collect a repeated payment for a subscription order

After you have taken an initial payment and saved the customer's card, you can use the payments API to collect repeated payments for a subscription order. You will need the cardholder-initiated transaction identifier from the initial payment.

Perform a POST request to the payment gateway to collect a repeated payment for a subscription order.

curl https://eu-test.oppwa.com/v1/registrations/{registrationId}/payments \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
-d "entityId={channelId}" \
-d "amount=20.04" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "merchantTransactionId=P127" \
-d "standingInstruction.type=RECURRING" \
-d "standingInstruction.mode=REPEATED" \
-d "standingInstruction.source=MIT" \
-d "standingInstruction.recurringType=SUBSCRIPTION" \
-d "standingInstruction.initialTransactionId={CardholderInitiatedTransactionID}" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
-d "customParameters[CRMCustomerID]=CUST01" \
-d "customParameters[SubscriptionID]=S-00100" \
-d "customParameters[TransactionID]=P-00006000" \
-d "customParameters[StoreCredentialType]=MIT" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer {auth_token}"

Replace the example values with your values and replace the {channelId} and {auth_token} with your API credentials, and replace the {CardholderInitiatedTransactionID}with the value from your initial transaction.

Here are some notes about the parameters in this request.

Parameters	Notes
paymentType	Can be `DB` ("debit") or `PA` ("preauthorization"). For `PA`, use the back-office API to capture the payment.
merchantTransactionId	We recommend that you provide a unique identifier for each transaction.
standingInstruction.type	Set to `RECURRING`to specify that you will collect recurring payments.
standingInstruction.mode	Set to `REPEATED`to specify a repeated payment using a saved card
standingInstruction.source	Set to `MIT`to specify a merchant-initiated transaction where the customer is not present.
standingInstruction.recurringType	Set to `SUBSCRIPTION`.
CardHolderInitiatedTransactionID	Use the value of the `CardHolderInitiatedTransactionID` that you obtained from the results of the initial payment.
customer details	We recommend that you supply the customer's IP address.

When you are testing your integration, you can use the following parameters.

Parameter	Notes
testMode	This parameter is for the test environment only. Set to `EXTERNAL` to send the transaction to the acquirer's test environment. Set to `INTERNAL` to process the transaction in the gateway only.

For full details of all the parameters, see Gateway API reference.

Test a repeated payment

To test a repeated subscription payment in the gateway playground, use the Card-on-file endpoint for this request: Gateway documentation for Card on File. Here is some sample data with the parameters in the correct format.

entityId={channelId}
amount=20.04
currency=EUR
paymentType=DB
merchantTransactionId=P127
standingInstruction.type=RECURRING
standingInstruction.mode=REPEATED
standingInstruction.source=MIT
standingInstruction.recurringType=SUBSCRIPTION
standingInstruction.initialTransactionId={CardholderInitiatedTransactionID}
customParameters[CRMCustomerID]=CUST01
customParameters[SubscriptionID]=S-00100
customParameters[TransactionID]=P-00007000
customParameters[StoreCredentialType]=MIT
customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af
testMode=EXTERNAL

Example response

You will receive a JSON response like the one below, which shows an approved repeated payment.

{
  "id": "8ac7a4a2913518d80191365427cf6df3",
  "paymentType": "DB",
  "amount": "20.00",
  "currency": "EUR",
  "descriptor": "1898.2744.9887 ECOMChannel ",
  "merchantTransactionId": "P127",
  "result": {
    "code": "000.100.112",
    "description": "Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails": {
    "ExtendedDescription": "Approved",
    "clearingInstituteName": "SecureTrading Omnipay Demo",
    "ConnectorTxID1": "871495||false| MCC634276   ||0809|| ||RECURRING|01||true|true|true|012|1",
    "ConnectorTxID3": "422208871495|00|||1||0809084930|||||||||||||Berlin|",
    "connectorId": "422208871495",
    "ConnectorTxID2": "273114||8ac7a0b49133d4740191365429110996",
    "AcquirerResponse": "00",
    "reconciliationId": "1898.2744.9887",
    "merchantAccountId": "8ac7a4c890fc748b0190fe70998c0248",
    "CardholderInitiatedTransactionID": "MCC6342760809",
    "SchemeResponseCode": "00"
  },
  "customer": {
    "ip": "2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af"
  },
  "customParameters": {
    "CRMCustomerID": "CRM CUST01",
    "StoreCredentialType": "MIT",
    "SubscriptionID": "S-00100",
    "TransactionID": "P-00006000"
  },
  "risk": {
    "score": "0"
  },
  "buildNumber": "174903ec91870d5654938dd40f55da3b35036b23@2024-08-08 12:50:27 +0000",
  "timestamp": "2024-08-09 08:49:30+0000",
  "ndc": "8ac7a4c890fc748b0190fe6ad56b0241_cba6ed9849894d408f4feb5f8fb48848",
  "standingInstruction": {
    "source": "MIT",
    "type": "RECURRING",
    "mode": "REPEATED",
    "initialTransactionId": "MCC6342760809",
    "recurringType": "SUBSCRIPTION"
  },
  "source": "OPP",
  "paymentMethod": "CC",
  "shortId": "1898.2744.9887"
}

To interpret the payment response, see Transaction results. You can also use the id to manage the payment with the Backoffice API. See Backoffice API operations.

View the full technical integration guide

The Integration Guide provides a comprehensive playground with code samples in all major programming languages.

Questions? - Visit our website and chat to our payment experts to learn more about integrating our COPYandPAY iFrame checkout.

Recommended Reading

Recommended Reading