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 the gateway PCI compliance documentation.

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.

Create the 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)"

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

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

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

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 "createRegistration=true" \
-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 will be saving the card, you must use the following standingInstruction parameters.

Parameter	Instalment value	Subscription value	Metered value	One-click checkout value
type	`INSTALMENT`	`RECURRING`	`UNSCHEDULED`	`UNSCHEDULED`
mode	`INITIAL`	`INITIAL`	`INITIAL`	`INITIAL`
source	`CIT`	`CIT`	`CIT`	`CIT`
recurringType		`SUBSCRIPTION`	`STANDING_ORDER`
nnumberOfInstallments	`999`
expiry	`9999-12-31`	`9999-12-31`
frequency	`0001`	`0001`
createRegistration				`true`

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.

Testing the requests in the gateway playground

To test these requests, you can use the gateway playground at Gateway documentation and playground for synchronous payments and the following data.

entityId={channelId}
amount=20.00
currency=EUR
paymentType=DB
merchantTransactionId=P223
paymentBrand=VISA
card.number=47111000000000000
card.holder=Joe Smith
card.expiryMonth=05
card.expiryYear=2030
card.cvv=123
billing.street1=Calle Principal 123
billing.city=Barcelona
billing.country=ES
billing.postcode=08123
[email protected]
customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af
customer.givenName=Joe
customer.surname=Smith
customer.phone=34667666666
customer.merchantCustomerId=CUST11
shopperResultUrl=https://example.com/shopperresult
customer.browser.screenColorDepth=48
customer.browser.javaEnabled=false
customer.browser.language=en
customer.browser.screenHeight=1200
customer.browser.screenWidth=1600
customer.browser.timezone=60
customer.browser.challengeWindow=4
customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
threeDSecure.challengeIndicator=04
customParameters[3DS2_enrolled]=true
customParameters[3DS2_flow]=challenge
testMode=EXTERNAL

entityId={channelId}
amount=20.00
currency=EUR
paymentType=DB
merchantTransactionId=P223
paymentBrand=VISA
card.number=47111000000000000
card.holder=Joe Smith
card.expiryMonth=05
card.expiryYear=2030
card.cvv=123
billing.street1=Calle Principal 123
billing.city=Barcelona
billing.country=ES
billing.postcode=08123
[email protected]
customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af
customer.givenName=Joe
customer.surname=Smith
customer.phone=34667666666
customer.merchantCustomerId=CUST11
shopperResultUrl=https://example.com/shopperresult
customer.browser.screenColorDepth=48
customer.browser.javaEnabled=false
customer.browser.language=en
customer.browser.screenHeight=1200
customer.browser.screenWidth=1600
customer.browser.timezone=60
customer.browser.challengeWindow=4
customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
threeDSecure.challengeIndicator=04
customParameters[3DS2_enrolled]=true
customParameters[3DS2_flow]=challenge
standingInstruction.type=INSTALLMENT
standingInstruction.mode=INITIAL
standingInstruction.source=CIT
standingInstruction.numberOfInstallments=999
standingInstruction.expiry=9999-12-31
standingInstruction.frequency=0001
testMode=EXTERNAL

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

entityId={channelId}
amount=20.00
currency=EUR
paymentType=DB
merchantTransactionId=P223
paymentBrand=VISA
card.number=47111000000000000
card.holder=Joe Smith
card.expiryMonth=05
card.expiryYear=2030
card.cvv=123
billing.street1=Calle Principal 123
billing.city=Barcelona
billing.country=ES
billing.postcode=08123
[email protected]
customer.ip=2001:8a0:7f4b:1b00:dd4e:2bf6:1fb8:56af
customer.givenName=Joe
customer.surname=Smith
customer.phone=34667666666
customer.merchantCustomerId=CUST11
shopperResultUrl=https://example.com/shopperresult
customer.browser.screenColorDepth=48
customer.browser.javaEnabled=false
customer.browser.language=en
customer.browser.screenHeight=1200
customer.browser.screenWidth=1600
customer.browser.timezone=60
customer.browser.challengeWindow=4
customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
threeDSecure.challengeIndicator=04
customParameters[3DS2_enrolled]=true
customParameters[3DS2_flow]=challenge
standingInstruction.type=UNSCHEDULED
standingInstruction.mode=INITIAL
standingInstruction.source=CIT
standingInstruction.recurringType=STANDING_ORDER
testMode=EXTERNAL

Use the following additional parameter to save a customer card in the gateway, for example, for one-click checkout.

createRegistration=true

When the payment is approved, get the registrationId from the response object and the 3DS data.

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.

Example responses

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

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

 {
  "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='downloadForm' 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='downloadForm' 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 are examples of the payment response for a single payment, and instalment and subscription payments.

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

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

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