Card Payments

General

Glossary

TermDescription
Recurring (requires recurrenceToken)Subscription type payment. E.g monthly debited amount for service.
Stored Card (requires paymentToken)Store card data from the consumer to allow future payments to be simplified.
Verification Transaction (operation Verify)Create a payment without charging the consumer. Use to create a recurrenceToken for recurring payment or paymentToken to store a card without charging an amount.

Payment Resource

The payment resource and all general sub-resources can be found in the core payment resources section.

Create Payment

Within the card payments part of the eCommerce API, you can create four kinds of payments  (purchase, recurrence, payout and verification) and you can inspect and alter the details of the individual transactions within the payment.

To create a card payment, you perform an HTTP POST against the /psp/creditcard/payments resource. Please read the general information on how to compose a valid HTTP request before proceeding.

There are four different kinds of payment that can be created. These are identified with the value of the operation property. Each kind are documented in their own section below.

All four payments have a common structure that is described below.  Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

POST /psp/creditcard/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "<operation>",
       "intent": "<intent>",
    }
}

Properties

PropertyData typeRequiredDescription
payment.operationstringY

Determines the initial operation, that defines the type card payment created. 

Purchase. Used to charge a card. It is followed up by a capture or cancel operation.

Recur. Used to charge a card on a recurring basis. Is followed up by a capture or cancel operation (if not Autocapture is used, that is).

Payout. Used to deposit funds directly to credit card. No more requests are necessary from the merchant side.

Verify. Used when authorizing a card withouth reserveing any funds.  It is followed up by a verification transaction.

payment.intentstringY

The intent of the payment identifies how and when the charge will be effectuated. This determine the type transactions used during the payment process.  

PreAuthorization. Holds the funds for a certain time in contrast to reserving the amount. A preauthoriations is always followed by the finalize operation

Authorization. Reserves the amount, and is followed by a cancellation or capture of funds.

AutoCapture. A one phase-option that enable capture of funds automatically after authorization.

The response will be as the payment resource is described above.

Purchase

A Purchase payment is a straightforward way to charge the card of the payer. It is followed up by posting a capture, cancellation or reversal transaction.

An example of a request is provided below. Each individual Property of the JSON document is described in the following section. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "Purchase",
       "intent": "Authorization",
       "paymentToken": "",
       "currency": "SEK",
       "prices": [{
               "type": "CreditCard",
               "amount": 1500,
               "vatAmount": 0
            },
            {
               "type": "Visa",
               "amount": 1500,
               "vatAmount": 0
            },
            {
               "type": "MasterCard",
               "amount": 1500,
               "vatAmount": 0
            }
        ],
       "description": "Test Purchase",
       "payerReference": "AB1234",
       "generatePaymentToken": "false",
       "generateRecurrenceToken": "false",
       "userAgent": "Mozilla/5.0...",
       "language": "sv-SE",
       "urls": {
           "hostUrls": ["http://test-dummy.net"],
           "completeUrl": "http://test-dummy.net/payment-completed",
           "cancelUrl": "http://test-dummy.net/payment-canceled",
           "paymentUrl": "http://example.com/perform-payment",
           "callbackUrl": "http://test-dummy.net/payment-callback",
           "logoUrl": "https://test-dummy.net/payment-logo.png",
           "termsOfServiceUrl": "https://test-dummy.net/payment-terms.pdf",
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "CD1234",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference": "or123",
           "subsite": "MySubsite"
        },
       "metadata": {
           "key1": "value1",
           "key2": 2,
           "key3": 3.1,
           "key4": false
        },
       "cardholder": {
           "firstName": "firstname/companyname",
           "lastName": "lastname",
           "email": "string",
           "msisdn": "string",
           "homePhoneNumber": "string",
           "workPhoneNumber": "string",
           "shippingAddress": {
               "firstName": "firstname",
               "lastName": "lastname",
               "email": "string",
               "msisdn": "string",
               "streetAddress": "string",
               "coAddress": "string",
               "city": "string",
               "zipCode": "string",
               "countryCode": "string"
            },
           "billingAddress": {
               "firstName": "firstname/companyname",
               "lastName": "lastname",
               "email": "string",
               "msisdn": "string",
               "streetAddress": "string",
               "coAddress": "string",
               "city": "string",
               "zipCode": "string",
               "countryCode": "string"
            },
           "accountInfo": {
               "accountAgeIndicator": "01",
               "accountChangeIndicator": "01",
               "accountPwdChangeIndicator": "01",
               "shippingAddressUsageIndicator": "01",
               "shippingNameIndicator": "01",
               "suspiciousAccountActivity": "01",
               "addressMatchIndicator": "false"
            }
        },
       "riskIndicator": {
           "deliveryEmailAddress": "string",
           "deliveryTimeFrameindicator": "01",
           "preOrderDate": "YYYYMMDD",
           "preOrderPurchaseIndicator": "01",
           "shipIndicator": "01",
           "giftCardPurchase": "false",
           "reOrderPurchaseIndicator": "01",
           "pickUpAddress": {
               "name": "companyname",
               "streetAddress": "string",
               "coAddress": "string",
               "city": "string",
               "zipCode": "string",
               "countryCode": "string"
            }
        }
    },
   "creditCard": {
       "rejectCreditCards": false,
       "rejectDebitCards": false,
       "rejectConsumerCards": false,
       "rejectCorporateCards": false,
    }
}
PropertyData typeRequiredDescription
operationstringYPurchase
intentstringY

PreAuthorization. Holds the funds for a certain time in contrast to reserving the amount. A preauthoriations is always followed by the finalize operation

Authorization. Reserves the amount, and is followed by a cancellation or capture of funds.

AutoCapture. A one phase option that enable capture of funds automatically after authorization.

paymentTokenstringNIf you put in a paymentToken here, the payment page will preload the stored payment data related to the paymentToken and let the consumer make a purchase without having to enter all card data. This is called a "One Click" purchase.
currencystringYNOK, SEK, DKK, USD or EUR.
prices.typestringY

Use the generic type CreditCard if you want to enable all card brands supported by merchant contract. Use card brands like Visa (for card type Visa), MasterCard (for card type Mastercard) and others if you want to specify different amount for each card brand. If you want to use more than one amount you must have one instance in the prices node for each card brand. You will not be allowed to both specify card brands and CreditCard at the same time in this field. See the Prices resource and prices object types for more information.

prices.amountintegerYAmount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
prices.vatAmountintegerYIf the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
descriptionstring(40)YA textual description max 40 characters of the purchase.
payerReferencestringNThe reference to the payer (consumer/end user) from the merchant system. E.g mobile number, customer number etc.
generatePaymentTokenbooleanNtrue or false. Set this to true if you want to create a paymentToken for future use as One Click.
generateRecurrenceTokenbooleanNtrue or false. Set this to true if you want to create a recurrenceToken for future use Recurring purchases (subscription payments).
userAgentstringYThe user agent reference of the consumer's browser - see user agent definition
languagestringYnb-NO, sv-SE or en-US.
urls.hostUrlarrayNThe array of URLs valid for embedding of PayEx Hosted Views. If not supplied, view-operation will not be available.
urls.completeUrlstringYThe URL that PayEx will redirect back to when the payment page is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both. 
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. If both cancelUrl and paymentUrl is sent, the paymentUrl will used.
urls.callbackUrlstringNThe URL that PayEx will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
urls.logoUrlstringNThe URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Require https.
urls.termsOfServiceUrlstringNA URL that contains your terms and conditions for the payment, to be linked on the payment page. Require https.
payeeInfo.payeeIdstringYThis is the unique id that identifies this payee (like merchant) set by PayEx.
payeeInfo.payeeReferencestring(30*)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
payeeInfo.payeeNamestringNThe payee name (like merchant name) that will be displayed to consumer when redirected to PayEx.
payeeInfo.productCategorystringNA product category or number sent in from the payee/merchant. This is not validated by PayEx, but will be passed through the payment process and may be used in the settlement process.
payeeInfo.orderReferenceString(50)NThe order reference should reflect the order reference found in the merchant's systems.
payeeInfo.subsiteString(40)NThe subsite field can be used to perform split settlement on the payment. The subsites must be resolved with PayEx reconciliation before being used.
metadataobjectNThe keys and values that should be associated with the payment. Can be additional identifiers and data you want to associate with the payment.
cardholder.firstNamestringNOptional (increased chance for frictionless flow if set) If buyer is a company, use only firstName for companyName.
cardholder.lastNamestringNOptional (increased chance for frictionless flow if set) If buyer is a company, use only firstName for companyName.
cardholder.emailstringNOptional (increased chance for frictionless flow if set)
cardholder.msisdnstringNOptional (increased chance for frictionless flow if set)
cardholder.homePhoneNumberstringNOptional (increased chance for frictionless flow if set)
cardholder.workPhoneNumberstringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.firstNamestringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.lastNamestringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.emailstringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.msisdnstringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.streetAddressstringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.coAddressstringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.citystringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.zipCodestringNOptional (increased chance for frictionless flow if set)
cardholder.shippingAddress.countryCodestringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.firstNamestringNOptional (increased chance for frictionless flow if set) If buyer is a company, use only firstName for companyName.
cardholder.billingAddress.lastNamestringNOptional (increased chance for frictionless flow if set) If buyer is a company, use only firstName for companyName.
cardholder.billingAddress.emailstringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.msisdnstringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.streetAddressstringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.coAddressstringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.citystringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.zipCodestringNOptional (increased chance for frictionless flow if set)
cardholder.billingAddress.countryCodestringNOptional (increased chance for frictionless flow if set)
cardholder.accountInfoobjectN

Optional (increased chance for frictionless flow if set) 

If cardholder is known by merchant and have some kind of registered user then these fields can be set.

cardholder.accountInfo.accountAgeIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates the length of time that the payments account was enrolled in the cardholder's account with merchant.
01 (No account, guest)
02 (Created during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)

cardholder.accountInfo.accountChangeIndicatorstringN

Optional (increased chance for frictionless flow if set)

Length of time since the cardholder's account information with the merchant was changed. Including billing etc.
01 (Changed during transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)

cardholder.accountInfo.accountPwdChangeIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates the length of time since the cardholder's account with the merchant had a password change or account reset.
01 (No change)
02 (Changed during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)

cardholder.accountInfo.shippingAddressUsageIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates when the shipping address used for this transaction was first used with the merchant.
01 (This transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)

cardholder.accountInfo.shippingNameIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
01 (Account name identical to shipping name)
02 (Account name different than shipping name)

cardholder.accountInfo.suspiciousAccountActivitystringN

Optional (increased chance for frictionless flow if set)

Indicates whether merchant has experienced suspicious activity (including previous fraud) on the cardholder account.
01 (No suspicious activity has been observed)
02 (Suspicious activity has been observed)

cardholder.accountInfo.addressMatchIndicatorbooleanN

Optional (increased chance for frictionless flow if set)

Allows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.

riskIndicator.deliveryEmailAddressstringN

Optional (increased chance for frictionless flow if set)

For electronic delivery, the email address to which the merchandise was delivered.

riskIndicator.deliveryTimeFrameIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)

riskIndicator.preOrderDatestringN

Optional (increased chance for frictionless flow if set)

For a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"

riskIndicator.preOrderPurchaseIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)

riskIndicator.shipIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates shipping method chosen for the transaction.
01 (Ship to cardholder's billing address)
02 (Ship to another verified address on file with merchant)
03 (Ship to address that is different than cardholder's billing address)
04 (Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields)
05 (Digital goods, includes online services, electronic giftcards and redemption codes)
06 (Travel and Event tickets, not shipped)
07 (Other, e.g. gaming, digital service)

riskIndicator.giftCardPurchasebooleanN

Optional (increased chance for frictionless flow if set)

true if this is a purchase of a gift card.

riskIndicator.reOrderPurchaseIndicatorstringN

Optional (increased chance for frictionless flow if set)

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)

riskIndicator.pickUpAddressobjectNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.namestringNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.streetAddressstringNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.coAddressstringNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.citystringNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.zipCodestringNIf shipIndicator set to 4, then prefil this.
riskIndicator.pickUpAddress.countryCodestringNIf shipIndicator set to 4, then prefil this.
creditCard.rejectDebitCardsbooleanNtrue if debit cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectCreditCardsbooleanNtrue if credit cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectConsumerCardsbooleanNtrue if consumer cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectCorporateCardsbooleanNtrue if corporate cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": {
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "number": 1234567890,
   "instrument": "CreditCard",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "payerReference": "AB1234",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "prices": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices" },
   "transactions": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions" },
   "authorizations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations" },
   "captures": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures" },
   "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
   "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
   "urls" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
  },
 "operations": [
    {
     "href": "https://api.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
     "rel": "update-payment-abort",
     "method": "PATCH",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.payex.com/creditcard/payments/authorize/123456123412341234123456789012",
     "rel": "redirect-authorization",
     "method": "GET",
     "contentType": "text/html"
    },
    {
     "method": "GET",
     "href": "https://ecom.dev.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=123456123412341234123456789012",
     "rel": "view-authorization",
     "contentType": "application/javascript"
    }
  ]
}

Recur

A Recur payment is a payment that references a recurrenceToken created through a previous payment in order to charge the same card. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

POST /psp/creditcard/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "Recur",
       "intent": "Authorization|AutoCapture",
       "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
       "currency": "NOK",
       "amount": 1500,
       "vatAmount": 0,
       "description": "Test Recurrence",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "urls": {
           "callbackUrl": "http://test-dummy.net/payment-callback"
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "CD1234",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference": "or-12456",
           "subsite": "MySubsite"
        }
    }
}

Payout

A Payout payment is a deposit directly to credit card. This options is only valid as part of the Payout to Card add-on service. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

POST /psp/creditcard/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "Payout",
       "intent": "AutoCapture",
       "paymentToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
       "currency": "NOK",
       "amount": 1500,
       "vatAmount": 0,
       "description": "Test Payout",
       "userAgent": "Mozilla/5.0",
       "language": "nb-NO",
       "urls": {
           "callbackUrl": "http://test-dummy.net/payment-callback"
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "CD1234",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference": "or-12456",
           "subsite": "MySubsite"
        }
    }
}
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": {
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "number": 1234567890,
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Payout",
   "currency": "NOK",
   "amount": 1500,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Recurrence",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "nb-NO",
   "paymentToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "prices": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices" },
   "transactions": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions" },
   "authorizations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations" },
   "captures": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures" },
   "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
   "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
   "urls" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
  }
}

Verify

A Verify payment lets you post verifications to confirm the validity of card information, without reserving or charging any amount. This option is often used to initiate a recurring payment flow where you do not want to charge the consumer right away. Please note that all boolean credit card attributes involving rejection of certain card types are optional and set on contract level. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.    

Request

POST /psp/creditcard/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json      

{
 "payment": {
   "operation": "Verify",
   "currency": "NOK",
   "description": "Test Verification",
   "payerReference": "AB1234",
   "userAgent": "Mozilla/5.0...",
   "language": "nb-NO",
   "generatePaymentToken": true,
   "generateRecurrenceToken": false,
   "urls": {
     "hostUrls": ["http://test-dummy.net"],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://example.com/perform-payment",
     "logoUrl": "https://test-dummy.net/payment-logo.png",
     "termsOfServiceUrl": "https://test-dummy.net/payment-terms.html"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",
     "productCategory": "A123",
     "orderReference": "or-12456",
     "subsite": "MySubsite"
    }
  },
 "creditCard": {
   "rejectCreditCards": false,
   "rejectDebitCards": false,
   "rejectConsumerCards": false,
   "rejectCorporateCards": false
  }
}
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "number": 1234567890,
       "created": "2016-09-14T13:21:29.3182115Z",
       "updated": "2016-09-14T13:21:57.6627579Z",
       "operation": "Verify",
       "state": "Ready",
       "currency": "NOK",
       "amount": 0,
       "description": "Test Verification",
       "payerReference": "AB1234",
       "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
       "userAgent": "Mozilla/5.0",
       "language": "nb-NO",
       "transactions": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions" },
       "verifications": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications" },
       "urls" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
       "payeeInfo" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": [
        {
           "href": "https://api.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "rel": "update-payment-abort",
           "method": "PATCH",
           "contentType": "application/json"
        },
        {
           "href": "https://ecom.payex.com/creditcard/payments/verification/123456123412341234123456789012",
           "rel": "redirect-verification",
           "method": "GET",
           "contentType": "application/json"
        },
        {
           "method": "GET",
           "href": "https://ecom.dev.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=123456123412341234123456789012",
           "rel": "view-verification",
           "contentType": "application/javascript"
        },
         
        {
           "method": "POST",
           "href": "https://ecom.dev.payex.com/psp/creditcard/confined/payments/{paymentId:guid}/verifications",
           "rel": "direct-verification",
           "contentType": "application/json"
        }

    ]   
}   

Operations

When a payment resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations are available will vary depending on the state of the payment resource, what the access token is authorized to do, etc. A list of possible operations and their explanation is given below.

Operations
{
   "payment": {},
   "operations": [
        {
           "href": "http://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "rel": "update-payment-abort",
           "method": "PATCH"
        },
        {
           "href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/123456123412341234123456789012",
           "rel": "redirect-authorization",
           "method": "GET"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com//creditcard/core/scripts/client/px.creditcard.client.js?token=123456123412341234123456789012",
           "rel": "view-authorization",
           "contentType": "application/javascript"
        },
        {
           "href": "https://api-ecommerce.externalintegration.payex.com/creditcard/confined/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations",
           "rel": "direct-authorization",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures",
           "rel": "create-capture",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations",
           "rel": "create-cancellation",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals",
           "rel": "create-reversal",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/60ed0025-f75a-4240-8872-e8c08e6d7544",
           "rel": "update-authorization-finalize",
           "method": "PATCH"
        },
        {
           "href": "https://ecom.externalintegration.payex.com/creditcard/payments/verification/123456123412341234123456789012",
           "rel": "redirect-verification",
           "method": "GET",
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com//creditcard/core/scripts/client/px.creditcard.client.js?token=123456123412341234123456789012",
           "rel": "view-verification",
        },   
        {
           "method": "POST",
           "href": "https://ecom.externalintegration.payex.com/psp/creditcard/confined/payments/{paymentId:guid}/verifications",
           "rel": "direct-verification",
        }
    ]
}

Properties

PropertyDescription
hrefThe target URI to perform the operation against.
relThe name of the relation the operation has to the current resource.
methodThe HTTP method to use when performing the operation.

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operations

Operation Description
update-payment-abortAborts the payment before any financial transactions are performed.
redirect-authorizationContains the URI that is used to redirect the consumer to the PayEx Payment Pages containing the card authorization UI.
view-authorizationContains the JavaScript href that is used to embed  the card authorization UI directly on the webshop/merchant site
direct-authorizationUsed to create a card authorization without the need to redirect consumer (requires PCI-DSS compliance for customer).
create-captureCreates a capture transaction.
create-cancellationCreates a cancellation transaction.
create-reversalCreates a reversal transaction.
update-authorization-finalizeUsed to finalize an authorization.
redirect-verificationContains the URI that redirect the consumer to the PayEx Payment Pages containing the card verification UI. It is only applicable when using the verify operation.
view-verificationContains the URI that is used redirect the consumer to the PayEx Payment Pages containing the card verification UI.
direct-verificationUsed to verify directly without redirection. It is only applicable, if the payee is PCI approved, when using the verify operation.

Card transactions

All card specific transactions are described below. Read more about the general transaction resource here.

Verifications

The verifications resource contains information about verfication transactions made on a payment with the operation set to Verify.  

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
 "verifications": {
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications",
   "verificationList": [
      {
       "direct": false,
       "paymentToken": "12345678-1234-1234-1234-123456789012",
       "recurrenceToken": "12345678-1234-1234-1234-123456789013",
       "maskedPan": "123456xxxxxx1234",
       "expiryDate": "mm/yyyy",
       "panToken": "12345678-1234-1234-1234-123456789012",
       "cardBrand": "Visa",
       "cardType": "Credit",
       "issuingBank": "UTL MAESTRO",
       "countryCode": "999",
       "acquirerTransactionType": "3DSECURE",
       "issuerAuthorizationApprovalCode": "397136",
       "acquirerStan": "39736",
       "acquirerTerminalId": "39",
       "acquirerTransactionTime": "2017-08-29T13:42:18Z",
       "authenticationStatus": "Y",
       "nonPaymentToken": "string",
       "externalNonPaymentToken": "string",
       "externalSiteId": "string",
       "transactionInitiator": "CARDHOLDER",
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications/12345678-1234-1234-1234-123456789012",
       "transaction": {
         "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
         "created": "2019-08-13T10:22:05.7532436Z",
         "updated": "2019-08-13T10:22:11.2502878Z",
         "type": "Verification",
         "state": "Initialized|Completed|Failed",
         "number": 1234567890,
         "amount": 1000,
         "vatAmount": 2500,
         "description": "Test transaction",
         "payeeReference": "AH123456",
         "failedReason": "ExternalResponseError",
         "failedActivityName": "Verify",
         "failedErrorCode": "REJECTED_BY_ACQUIRER",
         "failedErrorDescription": "unknown error, response-code: 51",
         "isOperational": false,
         "problem": {
           "type": "https://api.payex.com/psp/errordetail/creditcard/acquirererror",
           "title": "Operation failed",
           "status": 403,
           "detail": "Unable to complete Authorization transaction, look at problem node!",
           "problems": [
              {
               "name": "ExternalResponse",
               "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
              }
            ]
          },
         "operations": []
        }
      }
    ]
  }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this verification transactions resource belongs to.
verifications.idstringThe relative URI of the current verification transactions resource.
verifications.verificationListarrayThe array of verification transaction objects.
verifications.verificationList[]objectThe verification transaction object described in the verification resource below.

The verifications resource contains information about an verification transaction made on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications/12345678-1234-1234-1234-123456789012 HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
 "verification": {
   "direct": false,
   "paymentToken": "12345678-1234-1234-1234-123456789012",
   "recurrenceToken": "12345678-1234-1234-1234-123456789013",
   "maskedPan": "123456xxxxxx1234",
   "expiryDate": "mm/yyyy",
   "panToken": "12345678-1234-1234-1234-123456789012",
   "cardBrand": "Visa",
   "cardType": "Credit",
   "issuingBank": "UTL MAESTRO",
   "countryCode": "999",
   "acquirerTransactionType": "3DSECURE",
   "issuerAuthorizationApprovalCode": "397136",
   "acquirerStan": "39736",
   "acquirerTerminalId": "39",
   "acquirerTransactionTime": "2017-08-29T13:42:18Z",
   "authenticationStatus": "Y",
   "nonPaymentToken": "string",
   "externalNonPaymentToken": "string",
   "externalSiteId": "string",
   "transactionInitiator": "CARDHOLDER",
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications/12345678-1234-1234-1234-123456789012",
   "transaction": {
     "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
     "created": "2019-08-13T10:22:05.7532436Z",
     "updated": "2019-08-13T10:22:11.2502878Z",
     "type": "Verification",
     "state": "Initialized|Completed|Failed",
     "number": 1234567890,
     "amount": 1000,
     "vatAmount": 2500,
     "description": "Test transaction",
     "payeeReference": "AH123456",
     "failedReason": "ExternalResponseError",
     "failedActivityName": "Verify",
     "failedErrorCode": "REJECTED_BY_ACQUIRER",
     "failedErrorDescription": "unknown error, response-code: 51",
     "isOperational": false,
     "problem": {
       "type": "https://api.payex.com/psp/errordetail/creditcard/acquirererror",
       "title": "Operation failed",
       "status": 403,
       "detail": "Unable to complete Authorization transaction, look at problem node!",
       "problems": [
          {
           "name": "ExternalResponse",
           "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
          }
        ]
      },
     "operations": []
    }
  }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this verification transaction resource belongs to.
verification.idstringThe relative URI of the current authorization transaction resource.
verification.cardBrandstringVisa, MasterCard, etc. The brand of the card.
verification.cardTypestringCredit Card or Debit Card. Indicates the type of card used for the verification.
verification.paymentTokenstringThe payment token created for the card used in the verification process.
verification.recurrenceTokenstringThe recurrence token created for the card used in the verification process.
verification.maskedPanstringThe masked PAN number of the card.
verification.expiryDatestringThe month and year of when the card expires.
verification.panTokenstringThe token representing the specific PAN of the card.
verification.transactionObjectThe object representation of the generic transaction resource.

Create verification transaction

The direct-verification operation creates an verification transaction directly whilst the redirect-verificationoperation redirects the consumer to PayEx Payment pages where the payment is verified.

Request
POST /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "creditCardIssuer": "Visa|Mc|..."
    }
}

Properties

PropertyData typeRequiredDescription
transaction.cardNumberstringYPrimary Account Number (PAN) of the card, printed on the face of the card.
transaction.cardExpiryMonthintegerYExpiry month of the card, printed on the face of the card.
transaction.cardExpiryYearintegerYExpiry year of the card, printed on the face of the card.
transaction.cardVerificationCodestringNCard verification code (CVC/CVV/CVC2), usually printed on the back of the card.
transaction.cardholderNamestringNName of the card holder, usually printed on the face of the card.

Response

The verification resource contains information about an verification transaction made towards a payment, as previously described.

Authorizations

The authorizations resource contains information about authorization transactions made on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
 "authorizations": {
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations",
   "authorizationList": [
      {
       "direct": false,
       "paymentToken": "12345678-1234-1234-1234-123456789012",
       "recurrenceToken": "12345678-1234-1234-1234-123456789013",
       "maskedPan": "123456xxxxxx1234",
       "expiryDate": "mm/yyyy",
       "panToken": "12345678-1234-1234-1234-123456789012",
       "cardBrand": "Visa",
       "cardType": "Credit",
       "issuingBank": "UTL MAESTRO",
       "countryCode": "999",
       "acquirerTransactionType": "3DSECURE",
       "issuerAuthorizationApprovalCode": "397136",
       "acquirerStan": "39736",
       "acquirerTerminalId": "39",
       "acquirerTransactionTime": "2017-08-29T13:42:18Z",
       "authenticationStatus": "Y",
       "nonPaymentToken": "string",
       "externalNonPaymentToken": "string",
       "externalSiteId": "string",
       "transactionInitiator": "CARDHOLDER",
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012",
       "transaction": {
         "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
         "created": "2019-08-13T10:32:21.861621Z",
         "updated": "2019-08-13T10:32:23.4271016Z",
         "type": "Authorization",
         "state": "Failed",
         "number": 1234567890,
         "amount": 1000,
         "vatAmount": 2500,
         "description": "Test transaction",
         "payeeReference": "AH123456",
         "failedReason": "ExternalResponseError",
         "failedActivityName": "Authorize",
         "failedErrorCode": "REJECTED_BY_ACQUIRER",
         "failedErrorDescription": "unknown error, response-code: 51",
         "isOperational": false,
         "problem": {
           "type": "https://api.payex.com/psp/errordetail/creditcard/acquirererror",
           "title": "Operation failed",
           "status": 403,
           "detail": "Unable to complete Authorization transaction, look at problem node!",
           "problems": [
              {
               "name": "ExternalResponse",
               "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
              }
            ]
          },
         "operations": []
        }
      }
    ]
  }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this authorization transactions resource belongs to.
authorizations.idstringThe relative URI of the current authorization transactions resource.
authorizations.authorizationListarrayThe array of authorization transaction objects.
authorizations.authorizationList[]objectThe authorization transaction object described in the authorization resource below.

The authorization resource contains information about an authorization transaction made on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012 HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
 "authorization": {
   "direct": false,
   "paymentToken": "12345678-1234-1234-1234-123456789012",
   "recurrenceToken": "12345678-1234-1234-1234-123456789013",
   "maskedPan": "123456xxxxxx1234",
   "expiryDate": "mm/yyyy",
   "panToken": "12345678-1234-1234-1234-123456789012",
   "cardBrand": "Visa",
   "cardType": "Credit",
   "issuingBank": "UTL MAESTRO",
   "countryCode": "999",
   "acquirerTransactionType": "3DSECURE",
   "issuerAuthorizationApprovalCode": "397136",
   "acquirerStan": "39736",
   "acquirerTerminalId": "39",
   "acquirerTransactionTime": "2017-08-29T13:42:18Z",
   "authenticationStatus": "Y",
   "nonPaymentToken": "string",
   "externalNonPaymentToken": "string",
   "externalSiteId": "string",
   "transactionInitiator": "CARDHOLDER",
   "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012",
   "transaction": {
     "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
     "created": "2019-08-13T10:32:21.861621Z",
     "updated": "2019-08-13T10:32:23.4271016Z",
     "type": "Authorization",
     "state": "Failed",
     "number": 1234567890,
     "amount": 1000,
     "vatAmount": 2500,
     "description": "Test transaction",
     "payeeReference": "AH123456",
     "failedReason": "ExternalResponseError",
     "failedActivityName": "Authorize",
     "failedErrorCode": "REJECTED_BY_ACQUIRER",
     "failedErrorDescription": "unknown error, response-code: 51",
     "isOperational": false,
     "problem": {
       "type": "https://api.payex.com/psp/errordetail/creditcard/acquirererror",
       "title": "Operation failed",
       "status": 403,
       "detail": "Unable to complete Authorization transaction, look at problem node!",
       "problems": [
          {
           "name": "ExternalResponse",
           "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
          }
        ]
      },
     "operations": []
    }
  }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this authorization transaction resource belongs to.
authorization.idstringThe relative URI of the current authorization transaction resource.
authorization.paymentTokenstringThe payment token created for the card used in the authorization.
authorization.recurrenceTokenstringThe recurrence token created for the card used in the authorization.
authorization.maskedPanstringThe masked PAN number of the card.
authorization.expireDatestringThe month and year of when the card expires.
authorization.panTokenstringThe token representing the specific PAN of the card.
authorization.cardBrandstringVisa, MC, etc. The brand of the card.
authorization.cardTypestringCredit Card or Debit Card. Indicates the type of card used for the authorization.
authorization.issuingBankstringThe name of the bank that issued the card used for the authorization.
authorization.countryCodestringThe country the card is issued in.
authorization.acquirerTransactionTypestring3DSECURE or SSL. Indicates the transaction type of the acquirer.
authorization.acquirerStanstringThe System Trace Audit Number assigned by the acquirer to uniquely identify the transaction.
authorization.acquirerTerminalIdstringThe ID of the acquirer terminal.
authorization.acquirerTransactionTimestringThe ISO-8601 date and time of the acquirer transaction.
authorization.issuerAuthorizationApprovalCodestringThe issuer's six-digit code used to identify the approval for a specific authorization request.
authorization.authenticationStatusstringY, A, U or N. Indicates the status of the authentication.
authorization.transactionobjectThe object representation of the generic transaction resource.

Create authorization transaction

The direct-authorization operation creates an authorization transaction directly whilst the redirect-authorizationoperation redirects the consumer to PayEx Payment pages where the payment is authorized.

Note: In order to use the direct-authorization operation, the servers and application involved in retrieving and transferring the credit card number from the payer to PayEx needs to be PCI DSS certified.
Request
POST /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "cardNumber": "4925000000000004",
       "cardExpiryMonth": 11,
       "cardExpiryYear": 22,
       "cardVerificationCode": "185",
       "cardholderName": "John Hancock"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.cardNumberstringYPrimary Account Number (PAN) of the card, printed on the face of the card.
transaction.cardExpiryMonthintegerYExpiry month of the card, printed on the face of the card.
transaction.cardExpiryYearintegerYExpiry year of the card, printed on the face of the card.
transaction.cardVerificationCodestringNCard verification code (CVC/CVV/CVC2), usually printed on the back of the card.
transaction.cardholderNamestringNName of the card holder, usually printed on the face of the card.

Response

The authorization resource contains information about an authorization transaction made towards a payment, as previously described.

Captures

The captures resource list the capture transactions (one or more) on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

Response

HTTP/1.1 200 OK

Content-Type: application/json

 

{

    "payment""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",

    "captures": {

            "id""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures",

            "captureList": [{

                    "id""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures/12345678-1234-1234-1234-123456789012",

                    "transaction": {

                            "id""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",

                            "created""2016-09-14T01:01:01.01Z",

                            "updated""2016-09-14T01:01:01.03Z",

                            "type""Capture",

                            "state""Completed",

                            "number"1234567890,

                            "amount"1000,

                            "vatAmount"250,

                            "description""Test transaction",

                            "payeeReference""AH123456",

                            "failedReason""",

                            "isOperational"false,

                            "operations": []

                    }

            }]

    }

}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this list of capture transactions belong to.
captures.idstringThe relative URI of the current captures resource.
captures.captureListarrayThe array of capture transaction objects.
captures.captureList[]objectThe capture transaction object described in the capture resource below.

Create capture transaction

To create a capture transaction to withdraw money from the payer's card, you need to perform the create-capture operation.

Request

POST /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "amount": 1500,
       "vatAmount": 250,
       "description": "Test Capture",
       "payeeReference": "ABC123"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.amountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.vatAmountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.descriptionstringYA textual description of the capture transaction.
transaction.payeeReferencestring(30*)YA unique reference for the capture transaction. See payeeReference for details.

Response
The capture resource contains information about the capture transaction made against a card payment.

Response

HTTP/1.1 200 OK

Content-Type: application/json

 

{

    "payment""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",

    "capture": {

            "id""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures/12345678-1234-1234-1234-123456789012",

            "transaction": {

                   "id""/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",

                   "created""2016-09-14T01:01:01.01Z",

                   "updated""2016-09-14T01:01:01.03Z",

                   "type""Capture",

                   "state""Completed",

                   "number"1234567890,

                   "amount"1500,

                   "vatAmount"250,

                   "description""Test Capture",

                   "payeeReference""ABC123",

                   "isOperational"false,

                   "operations": []

            }

    }

}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
capture.idstringThe relative URI of the created capture transaction.
capture.transactionobjectThe object representation of the generic transaction resource.

Finalize

Finalizing a preauthorized payment is done as a PATCH  after a successful Authorization transaction has been created. The common use-case for the finalize operation is to authorize the payment (that has the preauthorization intent) and complete all payment related activities as soon as possible - in order to complete (finalize) everything server-to-server afterwards. The only allowed activity is Finalize. To use the operation, you should perform a GET on the payment after the user returns from the redirect-authorization operation and find the operation update-authorization-finalize.

Request

PATCH /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/<transactionId> HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "activity": "Finalize"
    }
}
PropertyData typeRequiredDescription
transaction.activitystringYFinalize
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "authorization": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012",
       "paymentToken": "12345678-1234-1234-1234-123456789012",
       "maskedPan": "123456xxxxxx1234",
       "expireDate": "mm/yyyy",
       "panToken": "12345678-1234-1234-1234-123456789012",
       "cardBrand": "Visa|MC",
       "cardType": "Credit Card|Debit Card",
       "issuingBank": "UTL MAESTRO",
       "countryCode": "999",
       "acquirerTransactionType": "3DSECURE|SSL",
       "acquirerStan": "39736",
       "acquirerTerminalId": "39",
       "acquirerTransactionTime": "2017-08-29T13:42:18Z",
       "authenticationStatus": "Y|A|U|N",
       "transaction": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Authorization",
           "state": "Initialized",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": true,
           "operations": [
                {
                   "href": "https://api.payex.com/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
                   "rel": "edit-authorization",
                   "method": "PATCH"
                }
            ]
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this finalize transaction resource belongs to.
authorizationobjectThe object representation of the authorization transaction resource.

Cancellations

The cancellations resource lists the cancellation transactions on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "cancellations": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations",
       "cancellationList": [{
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations/12345678-1234-1234-1234-123456789012",
           "transaction": {
               "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
               "created": "2016-09-14T01:01:01.01Z",
               "updated": "2016-09-14T01:01:01.03Z",
               "type": "Cancellation",
               "state": "Completed",
               "number": 1234567890,
               "amount": 1000,
               "vatAmount": 250,
               "description": "Test transaction",
               "payeeReference": "AH123456",
               "failedReason": "",
               "isOperational": false,
               "operations": []
            }
        }]
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this list of cancellation transactions belong to.
cancellations.idstringThe relative URI of the current cancellations resource.
cancellations.cancellationListarrayThe array of the cancellation transaction objects.
cancellations.cancellationList[]objectThe object representation of the cancellation transaction resource described below.

Create cancellation transaction

Perform the create-cancel operation to cancel a previously created - and not yet captured - payment.

Request

POST /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "description": "Test Cancellation",
       "payeeReference": "ABC123"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.descriptionstringYA textual description of the reason for the cancellation.
transaction.payeeReferencestring(30*)YA unique reference for the cancellation transaction. See payeeReference for details.

The cancel resource contains information about a cancellation transaction made against a payment.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "cancellation": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations/12345678-1234-1234-1234-123456789012",
       "transaction": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Cancellation",
           "state": "Initialized",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test Cancellation",
           "payeeReference": "ABC123",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this cancellation transaction belongs to.
cancellation.idstringThe relative URI of the current cancellation transaction resource.
cancellation.transactionobjectThe object representation of the generic transaction resource.

Reversals

The reversals resource lists the reversal transactions (one or more) on a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversals": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversal",
       "reversalList": [{
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversal/12345678-1234-1234-1234-123456789012",
           "transaction": {
               "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
               "created": "2016-09-14T01:01:01.01Z",
               "updated": "2016-09-14T01:01:01.03Z",
               "type": "Reversal",
               "state": "Completed",
               "number": 1234567890,
               "amount": 1000,
               "vatAmount": 250,
               "description": "Test transaction",
               "payeeReference": "AH123456",
               "failedReason": "",
               "isOperational": false,
               "operations": []
            }
        }]
    }
}

Properties

PropertyTypeDescription
paymentstringThe relative URI of the payment that the reversal transactions belong to.
idstringThe relative URI of the created reversal transaction.
reversalListarrayThe array of reversal transaction objects.
reversalList[]objectThe reversal transaction object representation of the reversal transaction resource described below.

Create reversal transaction

The create-reversal operation will reverse a previously captured payment.

Request

POST /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "amount": 1500,
       "vatAmount": 0,
       "description": "Test Reversal",
       "payeeReference": "ABC123"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.amountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.vatAmountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.descriptionstringYA textual description of the capture
transaction.payeeReferencestring(30*)YA unique reference for the reversal transaction. See payeeReference for details.

The reversal resource contains information about the newly created reversal transaction.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversal": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversal/12345678-1234-1234-1234-123456789012",
       "transaction": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Reversal",
           "state": "Completed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this reversal transaction belongs to.
reversal.idstringThe relative URI of the created reversal transaction.
reversal.transactionobjectThe object representation of the generic transaction resource.

Remove payment token

If you, for any reason, need to delete a paymentToken you use the Delete payment token request.

Please note that this call does not erase the card number stored at PayEx. A card number is automatically deleted six months after a successful Delete payment token request. If you want to remove card information beforehand, you need to contact support.ecom@payex.com; and supply them with the relevant transaction reference or payment token.

Request
PATCH /psp/creditcard/payments/instrumentData/<paymentToken> HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
 "state": "Deleted",
 "tokenType" : "PaymentToken|RecurrenceToken",
 "comment": "Comment on why the deletion is happening"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "instrumentData": {
   "id": "/psp/creditcard/payments/instrumentdata/12345678-1234-1234-1234-123456789000",
   "paymentToken": "12345678-1234-1234-1234-123456789000",
   "payeeId": "61c65499-de5c-454e-bf4c-043f22538d49",
   "isDeleted": true|false,
   "isPayeeToken": false,
   "cardBrand": "Visa|MasterCard|...",
   "maskedPan": "123456xxxxxx1111",
   "expiryDate": "MM/YYYY"
  }
}

Callback

When a change or update from the back-end system are made on a payment or transaction, PayEx will perform a callback to inform the payee (merchant) about this update. Callback functionality is explaned in more detail here.

Problem messages

When performing unsuccessful operations, the eCommerce API will respond with a problem message. We generally use the problem message type and status code to identify the nature of the problem. The problem name and description will often help narrow down the specifics of the problem.

For general information about problem messages and error handling, visit error handling and problem details. 

Contractual error types

All contract types will have the following URI in front of type: https://api.payex.com/psp/<errordetail>/creditcard

TypeStatusNotes
cardbranddisabled403 
accountholdertyperejected403 
cardtyperejected403 
3dsecurerequired403 
authenticationstatusrejected403 
frauddetected403 
3dsecuredeclined403 

Error types from 3Dsecure/ Acquirer

All acquirer error types will have the following URI in front of type: https://api.payex.com/psp/errordetail/creditcard/<errorType>

TypeStatusNotes
3dsecureerror4003D Secure not working, try again some time later
cardblacklisted400Card blacklisted, Consumer need to contact their Card-issuing bank
paymenttokenerror403  
carddeclined403 
acquirererror403 
acquirercardblacklisted403Card blacklisted, Consumer need to contact their Card-issuing bank
acquirercardexpired403Wrong expire date or Card has expired and consumer need to contact their Card-issuing bank
acquirercardstolen403Card blacklisted, Consumer need to contact their Card-issuing bank
acquirerinsufficientfunds403Card does not have sufficient funds, consumer need to contact their Card-issuing bank.
acquirerinvalidamount403Amount not valid by aquirer, contact support.ecom@payex.com
acquirerpossiblefraud403Transaction declined due to possible fraud, consumer need to contact their Card-issuing bank.
3dsecureusercanceled403Transaction was Cancelled during 3DSecure verification
3dsecuredeclined403Transaction was declined during 3DSecure verification
frauddetected403Fraud detected. Consumer need to contact their Card-issuing bank.
badrequest500Bad request, try again after some time
internalservererror500Server error, try again after some time
3dsecureacquirergatewayerror502Problems reaching 3DSecure verification, try again after some time.
badgateway502Problems reaching the gateway, try again after some time
acquirergatewayerror502Problems reaching acquirers gateway, try again after some time
acquirergatewaytimeout504Problems reaching acquirers gateway, try again after some time 
Created by Fredrik Köhler on 2018/10/26 11:08