Single or initial payment with gateway 3DS

From a PCI DSS-compliant environment, create a direct server-to-server integration with the CardCorp gateway.

🚧
PCI -DSS 4.x
Your website payment pages must comply with PCI DSS v4.x.
For more details, see https://cardcorp.docs.oppwa.com/tutorials/pci

Learn how to perform an initial payment with 3DS validation with the CardCorp gateway MPI. For instalment, subscription, or metered payments, add the appropriate parameters for an initial payment.

1. Create the payment request

Use a POSTrequest to the gateway to the payments endpoint with the payment type, amount, currency, and required attributes.

Here is an example of the request to create a single payment, instalment, subscription, or metered orders, and how to save a card in the payment gateway for one-click checkout.

Single payment request

curl https://eu-test.oppwa.com/v1/payments \
-d "entityId=(Channel ID)" \
-d "amount=20.00" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "merchantTransactionId=P123" \
-d "paymentBrand=VISA" \
-d "card.number=4711100000000000" \
-d "card.holder=Joe Smith" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2030" \
-d "card.cvv=123" \
-d "billing.street1=Ave. Diagonal 611" \
-d "billing.city=Barcelona" \
-d "billing.country=ES" \
-d "billing.postcode=08028" \
-d "[email protected]" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
-d "customer.givenName=Joe" \
-d "customer.surname=Smith" \
-d "customer.phone=442880090001" \
-d "customer.merchantCustomerId=CUST01" \
-d "shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server/standalone3DS#step3" \
-d "customer.browser.acceptHeader=text/html" \
-d "customer.browser.screenColorDepth=48" \
-d "customer.browser.javaEnabled=false" \
-d "customer.browser.language=en" \
-d "customer.browser.screenHeight=1200" \
-d "customer.browser.screenWidth=1600" \
-d "customer.browser.timezone=60" \
-d "customer.browser.challengeWindow=4" \
-d "customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)" \
-d "threeDSecure.challengeIndicator=04" \
-d "customParameters[3DS2_enrolled]=true" \
-d "customParameters[3DS2_flow]=challenge" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer (auth_token)"

Instalment request

curl https://eu-test.oppwa.com/v1/payments \
-d "entityId=(Channel ID)" \
-d "amount=200.00" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "merchantTransactionId=P123" \
-d "paymentBrand=VISA" \
-d "card.number=4711100000000000" \
-d "card.holder=Joe Smith" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2030" \
-d "card.cvv=123" \
-d "billing.street1=Ave. Diagonal 611" \
-d "billing.city=Barcelona" \
-d "billing.country=ES" \
-d "billing.postcode=08028" \
-d "[email protected]" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
-d "customer.givenName=Joe" \
-d "customer.surname=Smith" \
-d "customer.phone=442880090001" \
-d "customer.merchantCustomerId=CUST01" \
-d "shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server/standalone3DS#step3" \
-d "customer.browser.acceptHeader=text/html" \
-d "customer.browser.screenColorDepth=48" \
-d "customer.browser.javaEnabled=false" \
-d "customer.browser.language=en" \
-d "customer.browser.screenHeight=1200" \
-d "customer.browser.screenWidth=1600" \
-d "customer.browser.timezone=60" \
-d "customer.browser.challengeWindow=4" \
-d "customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)" \
-d "threeDSecure.challengeIndicator=04" \
-d "customParameters[3DS2_enrolled]=true" \
-d "customParameters[3DS2_flow]=challenge" \
-d "testMode=EXTERNAL" \
-d "standingInstruction.type=INSTALLMENT" \
-d "standingInstruction.mode=INITIAL" \
-d "standingInstruction.source=CIT" \
-d "standingInstruction.numberOfInstallments=999" \
-d "standingInstruction.expiry=9999-12-31" \
-d "standingInstruction.frequency=0001" \
-H "Authorization: Bearer (auth_token)"

Subscription request

curl https://eu-test.oppwa.com/v1/payments \
 -d "entityId={{channelId}}" \
 -d "amount=40.00" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -d "merchantTransactionId=P223" \
 -d "paymentBrand=MASTER" \
 -d "card.number=5200000000000049" \
 -d "card.holder=Bob Smith" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2030" \
 -d "card.cvv=123" \
 -d "billing.street1=Calle Principal 123" \
 -d "billing.city=Barcelona" \
 -d "billing.country=ES" \
 -d "billing.postcode=08123" \
 -d "[email protected]" \
 -d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
 -d "customer.givenName=Bob" \
 -d "customer.surname=Smith" \
 -d "customer.phone=34667666666" \
 -d "customer.merchantCustomerId=CUST12" \
 -d "shopperResultUrl=https://example.com" \
 -d "customer.browser.screenColorDepth=48" \
 -d "customer.browser.javaEnabled=false" \
 -d "customer.browser.language=en" \
 -d "customer.browser.screenHeight=1200" \
 -d "customer.browser.screenWidth=1600" \
 -d "customer.browser.timezone=60" \
 -d "customer.browser.challengeWindow=4" \
 -d "customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)" \
 -d "threeDSecure.challengeIndicator=04" \
 -d "customParameters[3DS_enrolled]=true" \
 -d "customParameters[3DS2_flow]=challenge" \
 -d "testMode=EXTERNAL" \
 -d "standingInstruction.type=RECURRING" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "standingInstruction.recurringType=SUBSCRIPTION" \
 -d "standingInstruction.expiry=9999-12-31" \
 -d "standingInstruction.frequency=0001" \
 -H "Authorization: Bearer {{auth_token}}"

Metered request

curl https://eu-test.oppwa.com/v1/payments \
-d "entityId=(Channel ID)" \
-d "amount=20.00" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "merchantTransactionId=P123" \
-d "paymentBrand=VISA" \
-d "card.number=4711100000000000" \
-d "card.holder=Joe Smith" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2030" \
-d "card.cvv=123" \
-d "billing.street1=Ave. Diagonal 611" \
-d "billing.city=Barcelona" \
-d "billing.country=ES" \
-d "billing.postcode=08028" \
-d "[email protected]" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af" \
-d "customer.givenName=Joe" \
-d "customer.surname=Smith" \
-d "customer.phone=442880090001" \
-d "customer.merchantCustomerId=CUST01" \
-d "shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server/standalone3DS#step3" \
-d "customer.browser.acceptHeader=text/html" \
-d "customer.browser.screenColorDepth=48"\
-d "customer.browser.javaEnabled=false"\
-d "customer.browser.language=en" \
-d "customer.browser.screenHeight=1200" \
-d "customer.browser.screenWidth=1600" \
-d "customer.browser.timezone=60" \
-d "customer.browser.challengeWindow=4" \
-d "customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)" \
-d "threeDSecure.challengeIndicator=04" \
-d "customParameters[3DS2_enrolled]=true" \
-d "customParameters[3DS2_flow]=challenge" \
-d "testMode=EXTERNAL" \
-d "standingInstruction.type=UNSCHEDULED" \
-d "standingInstruction.mode=INITIAL" \
-d "standingInstruction.source=CIT" \
-d "standingInstruction.recurringType=STANDING_ORDER" \
-H "Authorization: Bearer (auth_token)"

One-click checkout

curl https://eu-test.oppwa.com/v1/payments \
-d "entityId=(Channel ID)" \
-d "amount=20.00" \
-d "currency=EUR" \
-d "paymentType=DB" \
-d "merchantTransactionId=P123"\
-d "paymentBrand=VISA"\
-d "card.number=4711100000000000" \
-d "card.holder=Joe Smith" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2030" \
-d "card.cvv=123" \
-d "billing.street1=Ave. Diagonal 611" \
-d "billing.city=Barcelona" \
-d "billing.country=ES" \
-d "billing.postcode=08028" \
-d "standingInstruction.type=UNSCHEDULED" \
-d "standingInstruction.mode=INITIAL" \
-d "standingInstruction.source=CIT" \  
-d "createRegistration=true" \
-d "[email protected]" \
-d "customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af"\
-d "customer.givenName=Joe" \
-d "customer.surname=Smith" \
-d "customer.phone=442880090001" \
-d "customer.merchantCustomerId=CUST01" \
-d "shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server/standalone3DS#step3" \
-d "customer.browser.acceptHeader=text/html" \
-d "customer.browser.screenColorDepth=48"\
-d "customer.browser.javaEnabled=false"\
-d "customer.browser.language=en" \
-d "customer.browser.screenHeight=1200" \
-d "customer.browser.screenWidth=1600" \
-d "customer.browser.timezone=60" \
-d "customer.browser.challengeWindow=4" \
-d "customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)" \
-d "threeDSecure.challengeIndicator=04" \
-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 the above requests.

Parameters	Notes
paymentType	Can be `DB` ("debit"), `PA` ("preauthorisation"), or `CD` ("credit"). For `PA`, use the back-office API to capture the payment.
merchantTransactionId	We recommend that you provide a unique identifier for each transaction.
paymentBrand	`VISA`, `MASTER`
card details
billing address	The billing address is required if you are using 3DS verification; otherwise, it is recommended.
customer details	The customer `email` and `ip` are mandatory. The customer `givenName`, `surname`, `phone`, and `merchantCustomerId` are optional.
shopperResultUrl	A link to the web page where the customer will be redirected after payment. You should get the payment result and display it for the customer on that page. Only for 3DS.
customer browser	For 3DS, use these parameters to define a large browser window where 3DS displays to allow for different issuer implementation sizes.
threeDSecure.challengeIndicator	For 3DS, the recommended value is `04`. This means that 3DS is mandated in your region and it tells the issuer to define the challenge type. We recommend that you always use a 3DS challenge but for 3DS exemption, see the request example at Gateway playground SERVER-TO-SERVER data.
customParameters	You can send custom data in these parameters and the gateway will return it 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. For example, you can add custom parameters to uniquely identify the customer, order, and purchase type.

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

Parameters	Notes
customParameters[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]	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 a one-click checkout, from a single payment response, get the id, registrationId and 3DS parameters to use in repeated payment requests.

2. Get the 3DS redirect data from the response

The payment has a status of transaction pending because you must use the 3DS details in the response to redirect the cardholder to the 3DS system so they can verify the transaction.

Single-payment response

{
  "id":"8ac7a4a09167849e01916ae343dd3de8",
  "paymentType":"DB",
  "paymentBrand":"MASTER",
  "merchantTransactionId":"P223",
  "result":{
    "code":"000.200.000",
    "description":"transaction pending"
  },
  "resultDetails":{
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248"
  },
  "card":{
    "bin":"520000",
    "last4Digits":"0049",
    "holder":"Joe Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Joe",
    "surname":"Smith",
    "merchantCustomerId":"CUST11",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af",
    "browser":{
      "language":"en",
      "screenHeight":"1200",
      "screenWidth":"1600",
      "timezone":"60",
      "userAgent":"Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)",
      "javaEnabled":"false",
      "screenColorDepth":"48",
      "challengeWindow":"4"
    }
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "challengeIndicator":"04"
  },
  "customParameters":{
    "3DS2_flow":"challenge",
    "3DS_enrolled":"true"
  },
  "redirect":{
 "url":"https://test.oppwa.com/connectors/asyncresponse_simulator;jsessionid=AF479520ED64C237BE42DF8958D162B0.uat01-vm-con03?asyncsource=ACI_3DS_2&type=methodRedirect&cdkForward=true&ndcid=8ac7a4c890fc748b0190fe6ad56b0241_2e9b5ad5cb9a421eafda6c123119da27",
    "parameters":[
      
    ],
    "preconditions":[
      {
        "origin":"iframe#hidden",
        "waitUntil":"iframe#load",
        "description":"Hidden iframe post for 3D Secure 2.0",
        "url":"https://test.ppipe.net/connectors/demo/submit?action=ACI3DS2AccessControlServer&acsRequest=METHOD",
        "method":"POST",
        "parameters":[
          {
            "name":"threeDSMethodData",
            "value":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0Lm9wcHdhLmNvbS9jb25uZWN0b3JzL2FyX3NpbXVsYXRvci8zZHMyO2pzZXNzaW9uaWQ9QUY0Nzk1MjBFRDY0QzIzN0JFNDJERjg5NThEMTYyQjAudWF0MDEtdm0tY29uMDM_YXN5bmNzb3VyY2U9QUNJXzNEU18yJnR5cGU9bWV0aG9kTm90aWZpY2F0aW9uJm5kY2lkPThhYzdhNGM4OTBmYzc0OGIwMTkwZmU2YWQ1NmIwMjQxXzJlOWI1YWQ1Y2I5YTQyMWVhZmRhNmMxMjMxMTlkYTI3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxODlhMzk0Yy00MmY5LTQ0MDEtOTc1Zi1iYzcxM2U2NzE2NWYifQ"
          }
        ]
      }
    ]
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"58e6de7e1e6a0b42807a3a291ebd50fa46ba3ff9@2024-08-19 00:42:32 +0000",
  "timestamp":"2024-08-19 13:46:04+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_2e9b5ad5cb9a421eafda6c123119da27",
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"4476.6608.6311"
}

Instalment response

{
  "id":"8ac7a49f920e892301920f74654c2ec1",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "merchantTransactionId":"P223",
  "result":{
    "code":"000.200.000",
    "description":"transaction pending"
  },
  "resultDetails":{
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0042",
    "holder":"Joe Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Joe",
    "surname":"Smith",
    "merchantCustomerId":"CUST11",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af",
    "browser":{
      "language":"en",
      "screenHeight":"1200",
      "screenWidth":"1600",
      "timezone":"60",
      "userAgent":"Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)",
      "javaEnabled":"false",
      "screenColorDepth":"48",
      "challengeWindow":"4"
    }
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "challengeIndicator":"04"
  },
  "customParameters":{
    "3DS2_enrolled":"true",
    "3DS2_flow":"challenge"
  },
  "redirect":{
    "url":"https://test.oppwa.com/connectors/demo/submit?action=ACI3DS2AccessControlServer&ndcid=8ac7a4c890fc748b0190fe6ad56b0241_b57f164799354a1696b250a0018b878c&acsRequest=CHALLENGE&acsData=eyJUSFJFRURTU0VSVkVSX1VSTCI6Imh0dHBzOi8vdGVzdC5vcHB3YS5jb20vY29ubmVjdG9ycy9hcl9zaW11bGF0b3IvM2RzMjtqc2Vzc2lvbmlkPTVFMzcyMTdGQzBCOTE4QkQ4OTk3MDNDQTk3MUY4MDA0LnVhdDAxLXZtLWNvbjAxP2FzeW5jc291cmNlPUFDSV8zRFNfMiZ0eXBlPXJlc3VsdHMmbmRjaWQ9OGFjN2E0Yzg5MGZjNzQ4YjAxOTBmZTZhZDU2YjAyNDFfYjU3ZjE2NDc5OTM1NGExNjk2YjI1MGEwMDE4Yjg3OGMiLCJEU19UUkFOU19JRCI6IjVjMWI3OWYwLTFlN2UtNGFmOC05ZWIwLTNiOThjM2Q1ZjgwNyIsIkRBVEUiOiIyMC4wOS4yMDI0IiwiZGVsYXkiOiJOT05FIiwiVEhSRUVEU1NFUlZFUl9UUkFOU19JRCI6IjBmMTBkYTNkLWNlOGMtNDE5ZC05NWY0LWU2MTRiM2Y4MDlkNSIsIkFNT1VOVCI6IjIwLjAwIEVVUiIsIk5PVElGSUNBVElPTl9VUkwiOiJodHRwczovL3Rlc3Qub3Bwd2EuY29tL2Nvbm5lY3RvcnMvYXJfc2ltdWxhdG9yLzNkczI7anNlc3Npb25pZD01RTM3MjE3RkMwQjkxOEJEODk5NzAzQ0E5NzFGODAwNC51YXQwMS12bS1jb24wMT9hc3luY3NvdXJjZT1BQ0lfM0RTXzImdHlwZT1ub3RpZmljYXRpb24mbmRjaWQ9OGFjN2E0Yzg5MGZjNzQ4YjAxOTBmZTZhZDU2YjAyNDFfYjU3ZjE2NDc5OTM1NGExNjk2YjI1MGEwMDE4Yjg3OGMiLCJWRVJTSU9OIjoiMi4yLjAiLCJBQ1NfVFJBTlNfSUQiOiIzNDU4NTA5YS0wNmE2LTRkMGItOTM0Ni04Y2UwYzBiMjJjMzQiLCJERVZJQ0VfQ0hBTk5FTCI6IjAyIiwiU0VSVklDRV9UWVBFIjoiVmVyaWZpZWRCeVZJU0EiLCJDQVJEX05VTUJFUiI6IioqKioqKioqKioqKjAwNDIifQ",
    "parameters":[
      {
        "name":"creq",
       "value":"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIwZjEwZGEzZC1jZThjLTQxOWQtOTVmNC1lNjE0YjNmODA5ZDUiLCJhY3NUcmFuc0lEIjoiMzQ1ODUwOWEtMDZhNi00ZDBiLTkzNDYtOGNlMGMwYjIyYzM0IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0"
      },
      {
        "name":"threeDSSessionData",
        "value":""
      }
    ]
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"1cfd04285b5f3f0d214470ddad0137b7b0eb8047@2024-09-19 08:03:22 +0000",
  "timestamp":"2024-09-20 12:42:19+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_b57f164799354a1696b250a0018b878c",
  "standingInstruction":{
    "source":"CIT",
    "type":"INSTALLMENT",
    "mode":"INITIAL",
    "expiry":"9999-12-31",
    "frequency":"0001",
    "numberOfInstallments":"999"
  },
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"0715.8500.1591"
}

Subscription response

 {
  "id":"8ac7a4a2920e914401920f1b5be9780a",
  "paymentType":"DB",
  "paymentBrand":"MASTER",
  "merchantTransactionId":"P223",
  "result":{
    "code":"000.200.000",
    "description":"transaction pending"
  },
  "resultDetails":{
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248"
  },
  "card":{
    "bin":"520000",
    "last4Digits":"0049",
    "holder":"Bob Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Bob",
    "surname":"Smith",
    "merchantCustomerId":"CUST12",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af",
    "browser":{
      "language":"en",
      "screenHeight":"1200",
      "screenWidth":"1600",
      "timezone":"60",
      "userAgent":"Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)",
      "javaEnabled":"false",
      "screenColorDepth":"48",
      "challengeWindow":"4"
    }
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "challengeIndicator":"04"
  },
  "customParameters":{
    "3DS2_flow":"challenge",
    "3DS_enrolled":"true"
  },
  "redirect":{
 "url":"https://test.oppwa.com/connectors/asyncresponse_simulator;jsessionid=70FD9D6DAD3C06CEEEBE3A3DC9C70CF6.uat01-vm-con04?asyncsource=ACI_3DS_2&type=methodRedirect&cdkForward=true&ndcid=8ac7a4c890fc748b0190fe6ad56b0241_0d57153e0640489083fd9e8d560f044c",
    "parameters":[
      
    ],
    "preconditions":[
      {
        "origin":"iframe#hidden",
        "waitUntil":"iframe#load",
        "description":"Hidden iframe post for 3D Secure 2.0",
        "url":"https://test.ppipe.net/connectors/demo/submit?action=ACI3DS2AccessControlServer&acsRequest=METHOD",
        "method":"POST",
        "parameters":[
          {
            "name":"threeDSMethodData",
            "value":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0Lm9wcHdhLmNvbS9jb25uZWN0b3JzL2FyX3NpbXVsYXRvci8zZHMyO2pzZXNzaW9uaWQ9NzBGRDlENkRBRDNDMDZDRUVFQkUzQTNEQzlDNzBDRjYudWF0MDEtdm0tY29uMDQ_YXN5bmNzb3VyY2U9QUNJXzNEU18yJnR5cGU9bWV0aG9kTm90aWZpY2F0aW9uJm5kY2lkPThhYzdhNGM4OTBmYzc0OGIwMTkwZmU2YWQ1NmIwMjQxXzBkNTcxNTNlMDY0MDQ4OTA4M2ZkOWU4ZDU2MGYwNDRjIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhZDlmY2Q0ZC1hNDZkLTQ0ODMtODZjOS0yNGExOTY2MjFlYmMifQ"
          }
        ]
      }
    ]
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"1cfd04285b5f3f0d214470ddad0137b7b0eb8047@2024-09-19 08:03:22 +0000",
  "timestamp":"2024-09-20 11:05:04+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_0d57153e0640489083fd9e8d560f044c",
  "standingInstruction":{
    "source":"CIT",
    "type":"RECURRING",
    "mode":"INITIAL",
    "expiry":"9999-12-31",
    "frequency":"0001",
    "recurringType":"SUBSCRIPTION"
  },
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"7707.2557.6823"
}

Get the id of the payment so you can use it later to get the payment status.

And get the redirect data for processing the 3DS verification.

📘
Gateway documentation
For the gateway documentation and playground for this request go to Gateway documentation for server to server and in the Use cases section select Synchronous payment.
We add the 3DS parameters to the payment request as shown above. But the gateway documentation and playground for 3DS verification is at Gateway documentation for standalone 3DS.

2. Handle the 3DS redirect

To perform the 3DS verification, get the redirect to perform the 3DS verification from the redirect attribute of the above response. For example.

Handle 3DS redirect

  "redirect":{
    "url":"https://test.oppwa.com/connectors/asyncresponse_simulator;jsessionid=AF479520ED64C237BE42DF8958D162B0.uat01-vm-con03?asyncsource=ACI_3DS_2&type=methodRedirect&cdkForward=true&ndcid=8ac7a4c890fc748b0190fe6ad56b0241_2e9b5ad5cb9a421eafda6c123119da27",
    "parameters":[  
    ],
    "preconditions":[
      {
        "origin":"iframe#hidden",
        "waitUntil":"iframe#load",
        "description":"Hidden iframe post for 3D Secure 2.0",
        "url":"https://test.ppipe.net/connectors/demo/submit?action=ACI3DS2AccessControlServer&acsRequest=METHOD",
        "method":"POST",
        "parameters":[
          {
            "name":"threeDSMethodData",
            "value":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0Lm9wcHdhLmNvbS9jb25uZWN0b3JzL2FyX3NpbXVsYXRvci8zZHMyO2pzZXNzaW9uaWQ9QUY0Nzk1MjBFRDY0QzIzN0JFNDJERjg5NThEMTYyQjAudWF0MDEtdm0tY29uMDM_YXN5bmNzb3VyY2U9QUNJXzNEU18yJnR5cGU9bWV0aG9kTm90aWZpY2F0aW9uJm5kY2lkPThhYzdhNGM4OTBmYzc0OGIwMTkwZmU2YWQ1NmIwMjQxXzJlOWI1YWQ1Y2I5YTQyMWVhZmRhNmMxMjMxMTlkYTI3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxODlhMzk0Yy00MmY5LTQ0MDEtOTc1Zi1iYzcxM2U2NzE2NWYifQ"
          }
        ]
      }
    ]
  },

To perform the 3DS redirect, do these steps:

From the redirect attribute
1. Get the preconditions.url and the preconditions.parameters array, which can have multiple key value pairs with name and value attributes.
2. Get the url and parameters array from the redirect object

Open a hidden iframe and make a POST request to the preconditions url in the following format.

<form name='' action='preconditions.url' method='POST'>
    <INPUT type='hidden' name='preconditions.parameters[].name' value='preconditions.parameters[].value'>
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>

Create another iframe where the cardholder will see the authentication request from their bank.

<form name='' action='redirect.URL' method='POST'>
    <INPUT type='hidden' name='redirect.parameters[].name' value='redirect.parameters[].value'>
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>

Add the key/value pairs from the redirect.parameters[] array.
Use a separate page so that the issuer authentication page always displays correctly.

Listen and wait for the onLoad() event from the preconditions step, then redirect the shopper within the iframe to the redirect.url.

The gateway documentation and playground for this step is at Gateway documentation for standalone 3DS under 2. How to handle the responses, but we are not using standalone 3DS.

3. Get the payment status

Get the payment result from the payments endpoint using a request in this format.

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

The gateway documentation and playground for this step is at Gateway documentation for asynchronous payments under 3. Get the payment status.

After the user performs the 3DS verification step, the user is redirected to the shopperResultUrl, and you can display the result of the payment there.

4. Check the payment response

Here is an example payment response for a single payment and instalment order.

Single payment payment response

{
  "id":"8ac7a4a1917803de01917aa40667038e",
  "paymentType":"PA",
  "paymentBrand":"VISA",
  "amount":"20.00",
  "currency":"EUR",
  "descriptor":"1101.0873.7831 ECOMChannel ",
  "merchantTransactionId":"P223",
  "result":{
    "avsResponse":"U",
    "cvvResponse":"P",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails":{
    "ExtendedDescription":"Approved",
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "ConnectorTxID1":"385390|U|true|VU        P||0822|331|Y|A |RECURRING|80||false|false|false|812|",
    "TxIdentifier":"822161055567902",
    "ConnectorTxID3":"423503385390|00|0170282216105556790200423A ||1||0822151055||||||||||||||",
    "connectorId":"423503385390",
    "ConnectorTxID2":"320983|822161055567902",
    "AcquirerResponse":"00",
    "reconciliationId":"1101.0873.7831",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248",
    "SchemeResponseCode":"00"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0042",
    "holder":"Joe Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Joe",
    "surname":"Smith",
    "merchantCustomerId":"CUST11",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af"
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.2.0",
    "dsTransactionId":"433ec799-d9db-49a6-9cdf-900acdbc79f2",
    "acsTransactionId":"fe3e7124-ec18-449b-b99e-6df46d18561a",
    "flow":"challenge",
    "authenticationStatus":"Y"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"58e6de7e1e6a0b42807a3a291ebd50fa46ba3ff9@2024-08-19 00:42:32 +0000",
  "timestamp":"2024-08-22 15:10:55+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_b5f3815268964e18a4f4ce9fb363e8c5",
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"1101.0873.7831"
}

Instalment payment response

{
  "id":"8ac7a4a1917803de01917ac1653a6e6e",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"700.00",
  "currency":"EUR",
  "descriptor":"8413.1982.5703 ECOMChannel ",
  "merchantTransactionId":"P223",
  "result":{
    "avsResponse":"U",
    "cvvResponse":"P",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails":{
    "ExtendedDescription":"Approved",
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "ConnectorTxID1":"385393|U|true|VU        P||0822|150|Y|A |INSTALLMENT|80||false|false|false|812|2",
    "TxIdentifier":"822164300567930",
    "ConnectorTxID3":"423503385393|00|0170282216430056793000423A ||1||0822154300||||||||||||||",
    "connectorId":"423503385393",
    "ConnectorTxID2":"464656|822164300567930|8ac7a0b3917a2b5801917ac1661c32d2",
    "AcquirerResponse":"00",
    "reconciliationId":"8413.1982.5703",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248",
    "CardholderInitiatedTransactionID":"822164300567930",
    "SchemeResponseCode":"00"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0042",
    "holder":"Joe Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Joe",
    "surname":"Smith",
    "merchantCustomerId":"CUST11",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af"
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.2.0",
    "dsTransactionId":"27bd2b0a-39b9-41ae-b5a4-e117386fbd45",
    "acsTransactionId":"d87e9449-e21a-4e09-a257-2ed9f0732818",
    "flow":"challenge",
    "authenticationStatus":"Y"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"58e6de7e1e6a0b42807a3a291ebd50fa46ba3ff9@2024-08-19 00:42:32 +0000",
  "timestamp":"2024-08-22 15:43:00+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_62a57d0cbc94414f8c27e2646f7fa8df",
  "standingInstruction":{
    "source":"CIT",
    "type":"INSTALLMENT",
    "mode":"INITIAL",
    "initialTransactionId":"822164300567930",
    "expiry":"9999-12-31",
    "frequency":"0001",
    "numberOfInstallments":"999"
  },
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"8413.1982.5703"
}

Subscription payment response

{
  "id":"8ac7a4a2920e914401920f0b298f7a45",
  "paymentType":"DB",
  "paymentBrand":"MASTER",
  "amount":"40.00",
  "currency":"EUR",
  "descriptor":"5259.0880.3703 ECOMChannel ",
  "merchantTransactionId":"P223",
  "result":{
    "cvvResponse":"U",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails":{
    "ExtendedDescription":"Approved",
    "clearingInstituteName":"SecureTrading Omnipay Demo",
    "ConnectorTxID1":"407510||true|UMCC776126   ||0920|581| ||RECURRING|80||false|false|true|812|1",
    "ConnectorTxID3":"426410407510|00|||1||0920104722|||||||||||||Berlin|",
    "PaymentAccountReference":"5665ABCDEFGHIJKLMNOPQRSTUVWXY",
    "connectorId":"426410407510",
    "ConnectorTxID2":"922513||8ac7a0b3920eee7101920f0b2aa6007b",
    "AcquirerResponse":"00",
    "reconciliationId":"5259.0880.3703",
    "merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248",
    "CardholderInitiatedTransactionID":"MCC7761260920",
    "SchemeResponseCode":"00"
  },
  "card":{
    "bin":"520000",
    "last4Digits":"0049",
    "holder":"Bob Smith",
    "expiryMonth":"05",
    "expiryYear":"2030"
  },
  "customer":{
    "givenName":"Bob",
    "surname":"Smith",
    "merchantCustomerId":"CUST12",
    "phone":"34667666666",
    "email":"[email protected]",
    "ip":"2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af",
    "browser":{
      "language":"en",
      "screenHeight":"1200",
      "screenWidth":"1600",
      "timezone":"60",
      "userAgent":"Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)",
      "javaEnabled":"false",
      "screenColorDepth":"48",
      "challengeWindow":"4"
    }
  },
  "billing":{
    "street1":"Calle Principal 123",
    "city":"Barcelona",
    "postcode":"08123",
    "country":"ES"
  },
  "threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.2.0",
    "dsTransactionId":"2e6923b9-b80f-4bee-bf91-75017d79c36f",
    "challengeIndicator":"04",
    "acsTransactionId":"f0503576-91e1-4e53-b86f-10ddc87fcb88",
    "flow":"challenge",
    "authenticationStatus":"Y"
  },
  "customParameters":{
    "3DS2_flow":"challenge",
    "3DS_enrolled":"true"
  },
  "risk":{
    "score":"0"
  },
  "buildNumber":"1cfd04285b5f3f0d214470ddad0137b7b0eb8047@2024-09-19 08:03:22 +0000",
  "timestamp":"2024-09-20 10:47:23+0000",
  "ndc":"8ac7a4c890fc748b0190fe6ad56b0241_bd59e0bb1f0e47dcbedbe6bc4cbdfa4a",
  "standingInstruction":{
    "source":"CIT",
    "type":"RECURRING",
    "mode":"INITIAL",
    "initialTransactionId":"MCC7761260920",
    "expiry":"9999-12-31",
    "frequency":"0001",
    "recurringType":"SUBSCRIPTION"
  },
  "source":"OPP",
  "paymentMethod":"CC",
  "shortId":"5259.0880.3703"
}

The above transactions were approved, as shown in this section. In a production environment, an approved transaction will have a result code of 000.000.000.

  "result":{
    "avsResponse":"U",
    "cvvResponse":"P",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },

If the transaction is declined, the result code will not be 000.000.000. For more details, see Transaction results.

If you are processing a recurring payment, the response should also contain the standingInstruction details.

5. Manage the payment

From the response for an approved payment, get the value of the payment id. You can use the id to manage the payment. You can capture a preauthorisation, refund a payment, or reverse a preauthorisation with the Backoffice API. See Backoffice API operations. You can also do the back office operations in the UI of Connect by CardCorp.

6. Process recurring payments

To process recurring payments, from the initial payment response also get the CardholderInitiatedTransactionID. See Repeated payment.

If you are creating a one-click checkout by saving the card in the payment gateway, also get the registrationId and the 3D secure data to create a repeated payment.

Single or initial payment with gateway 3DS

🚧
PCI -DSS 4.x

1. Create the payment request

2. Get the 3DS redirect data from the response

📘
Gateway documentation

2. Handle the 3DS redirect

3. Get the payment status

4. Check the payment response

5. Manage the payment

6. Process recurring payments

🚧PCI -DSS 4.x

1. Create the payment request

2. Get the 3DS redirect data from the response

📘Gateway documentation

2. Handle the 3DS redirect

3. Get the payment status

4. Check the payment response

5. Manage the payment

6. Process recurring payments

🚧
PCI -DSS 4.x

📘
Gateway documentation