From a PCI DSS-compliant environment, you can directly integrate with the SERVER-TO-SERVER API of 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 a single or initial payment with 3DS validation with your MPI. You must include parameters for initial payments for instalments, subscriptions, and metered orders.
1. Create the payment request
Create a POSTrequest to the gateway to the payments endpoint with the payment type, amount, currency, and required attributes.
The following example requests show how to create a payment that includes the information from a 3DS verification you performed with your MPI.
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 "threeDSecure.eci=05" \
-d "threeDSecure.authenticationStatus=Y" \
-d "threeDSecure.version=2.2.0" \
-d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
-d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f99364ecbd0e8" \
-d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
-d "threeDSecure.flow=challenge" \
-d "testMode=EXTERNAL" \
-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 "threeDSecure.eci=05" \
-d "threeDSecure.authenticationStatus=Y" \
-d "threeDSecure.version=2.2.0" \
-d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
-d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f99364ecbd0e8" \
-d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
-d "threeDSecure.flow=challenge" \
-d "testMode=EXTERNAL" \
-d "standingInstruction.type=INSTALMENT" \
-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=(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 "threeDSecure.eci=05" \
-d "threeDSecure.authenticationStatus=Y" \
-d "threeDSecure.version=2.2.0" \
-d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
-d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f99364ecbd0e8" \
-d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
-d "threeDSecure.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 "threeDSecure.eci=05" \
-d "threeDSecure.authenticationStatus=Y" \
-d "threeDSecure.version=2.2.0" \
-d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
-d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f99364ecbd0e8" \
-d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
-d "threeDSecure.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 "threeDSecure.eci=05" \
-d "threeDSecure.authenticationStatus=Y" \
-d "threeDSecure.version=2.2.0" \
-d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
-d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f99364ecbd0e8" \
-d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
-d "threeDSecure.flow=challenge" \
-d "testMode=EXTERNAL" \
-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 request.
| 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 recommended. |
| customer details | The customer email and ip are mandatory. The customer givenName, surname, phone, and merchantCustomerId are optional. |
| threeDSecure parameters | These parameters are from the results of a standalone 3DS verification. For an example of this type of verification in the CardCorp gateway and the response object with these attributes, see CardCorp gateway standalone 3DS documentation. |
| 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 |
|---|---|
| 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. |
Gateway documentation
For the gateway documentation and playground for this request go to Gateway server-to-server documentation and in the Use cases section select Synchronous payment.
2. Get payment response
Get the payment response and check the status of the payment. If the transaction is approved in a production environment, the result code will be 000.000.000. To interpret the payment response, see Transaction results.
Here is an example of a payment response for a single payment, as well as an initial instalment and initial subscription payment.
{
"id":"8ac7a4a1916ca6cd01916f71da0b0264",
"paymentType":"DB",
"paymentBrand":"MASTER",
"amount":"12.50",
"currency":"EUR",
"descriptor":"3296.8763.4471 ECOMChannel ",
"merchantTransactionId":"order99234",
"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":"279033||true|UMCC529869 ||0820|634| ||RECURRING|80||false|false|false|812|",
"ConnectorTxID3":"423311279033|00|||1||0820110018|||||||||||||Berlin|",
"connectorId":"423311279033",
"ConnectorTxID2":"471084||8ac7a0b3916eef4901916f71db0139c8",
"AcquirerResponse":"00",
"reconciliationId":"3296.8763.4471",
"merchantAccountId":"8ac7a4c890fc748b0190fe70998c0248",
"SchemeResponseCode":"00"
},
"card":{
"bin":"520000",
"last4Digits":"0049",
"holder":"John Smith",
"expiryMonth":"12",
"expiryYear":"2025"
},
"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":"6bea022c-9fa5-4a96-93bf-a2b3d9b7652a",
"acsTransactionId":"ef29e801-9366-4e07-8c4f-bdb40d2f73ec",
"flow":"challenge",
"authenticationStatus":"Y"
},
"risk":{
"score":"0"
},
"buildNumber":"58e6de7e1e6a0b42807a3a291ebd50fa46ba3ff9@2024-08-19 00:42:32 +0000",
"timestamp":"2024-08-20 11:00:18+0000",
"ndc":"8ac7a4c890fc748b0190fe6ad56b0241_7fe93f779ee54b0fb04a77590c407aaa",
"source":"OPP",
"paymentMethod":"CC",
"shortId":"3296.8763.4471"
} {
"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":"8ac7a4a1920e892301920f5fe1df2a2a",
"paymentType":"DB",
"paymentBrand":"VISA",
"amount":"20.00",
"currency":"EUR",
"descriptor":"3967.9709.6055 ECOMChannel ",
"merchantTransactionId":"P223",
"result":{
"avsResponse":"U",
"cvvResponse":"P",
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"resultDetails":{
"ConnectorTxID1":"407538|U|true|VU P||0920|071|Y|A |RECURRING|80||false|false|true|812|1",
"ConnectorTxID3":"426412407538|00|0170292013195577675800423A ||1||0920121954||||||||||||||",
"PaymentAccountReference":"VPARN000001000abcdefgh00000001",
"connectorId":"426412407538",
"ConnectorTxID2":"030537|920131955776758|8ac7a0b3920eee7101920f5fe35d022a",
"CardholderInitiatedTransactionID":"920131955776758",
"SchemeResponseCode":"00",
"ExtendedDescription":"Approved",
"clearingInstituteName":"SecureTrading Omnipay Demo",
"TxIdentifier":"920131955776758",
"AcquirerResponse":"00",
"reconciliationId":"3967.9709.6055",
"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"
},
"billing":{
"street1":"Calle Principal 123",
"city":"Barcelona",
"postcode":"08123",
"country":"ES"
},
"threeDSecure":{
"eci":"05",
"verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"version":"2.2.0",
"dsTransactionId":"41dd3f1d-59c8-4a64-a53a-7ca115b8c6a7",
"acsTransactionId":"ccdbebbd-2429-47d8-a347-bb44554ed364",
"flow":"challenge",
"authenticationStatus":"Y"
},
"risk":{
"score":"0"
},
"buildNumber":"1cfd04285b5f3f0d214470ddad0137b7b0eb8047@2024-09-19 08:03:22 +0000",
"timestamp":"2024-09-20 12:19:55+0000",
"ndc":"8ac7a4c890fc748b0190fe6ad56b0241_413077f410d44bf5ae1729f3bf51d226",
"standingInstruction":{
"source":"CIT",
"type":"RECURRING",
"mode":"INITIAL",
"initialTransactionId":"920131955776758",
"expiry":"9999-12-31",
"frequency":"0001",
"recurringType":"SUBSCRIPTION"
},
"source":"OPP",
"paymentMethod":"CC",
"shortId":"3967.9709.6055"
}From the payment response, get the value of the payment id to manage the payment.
If you are saving the customer's card in the gateway to create a one-click checkout, get the registrationId.
If your order will have repeated payments, get the CardHolderInitiatedTransactionID.
2. Get the payment status
Get the payment status from the payments endpoint with 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.
3. Manage the payment
Use the back office API to capture a pre-authorised amount, refund a payment, or reverse a pre-authorisation from the payments endpoint. Use the payment id from the payment response to identify the payment. See Backoffice API operations. You can also do these actions in the CardCorp Merchant Hub.
4. Get a repeated payment
If your payment was an initial payment for an instalment, subscription, or metered order, get the CardHolderInitiatedTransactionID to use in repeated payment requests. See Repeated payment.