PayEx Checkout

General

GLOSSARY

TermDescription
Recurring (requires recurrenceToken)Subscription type payment. E.g Monthly debited amount for service.
Stored Card Card data is saved on the consumers profile to allow future payments to be simplified.
Verification Transaction (operation Verify)Create a payment without debiting the consumer. Used to create a recurrenceToken for recurring payments without debiting an amount.

API Changes for 3DS2.0 in PaymentOrder

ChangeDescription
RemovedgeneratePaymentToken removed as stored card is handled by PayEx.
AddedgenerateRecurrenceToken added to create a token for recurring payments.
AddedPayer object and parameters added to allow decreased chance of authentication challenge flow.
RemovedSome CreditCard object-parameters removed as they will not be eligible in 3DS2.0. (E.g. no3DSecure: true).

Use Cases: Create Payment Order

There's three different Create Payment Order cases based on which kind of integration you're set to use.

IntegrationDefinition
PayEx CheckoutThe standard setup. The consumer provide details on PayEx end to create a new consumer profile or use an already existing profile of the consumer.
PayEx Checkout without CheckinAnonymous payment. No consumer profile will be created or used in the payment. Does not allow stored cards.
PayEx Checkout - Merchant onboardingThe advanced setup. The merchant provides consumer details and PayEx will create a new consumer profile or use an already existing profile of the consumer. An advanced setup needs a separate GDPR agreement and approval from PayEx.

1.0 Use Case: PayEx Checkout

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                               
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                   
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                      
     "orderReference" : "or-123456"                                
    },
   "payer": {
      "consumerProfileRef": "string",
      "email": "string",
      "msisdn": "string",
      "workPhoneNumber" : "string",                              
      "homePhoneNumber" : "string"                                 
    },
   "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"
       }
    },
   "metadata": {                                                 
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                                
    {
     "creditCard": {
       "rejectCreditCards": false,                           
       "rejectDebitCards": false,                           
       "rejectConsumerCards": false,                        
       "rejectCorporateCards": false                      
      }
    }
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false           
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted view. See URLs for details.
payeeInfo.payeeNamestringNThe name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.consumerProfileRefstringNThe consumer profile reference as obtained through the Consumers API.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.

1.1 Use Case: PayEx Checkout without Checkin

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dymmy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/compnayname",
       "lastName" : "lastname",               
       "email": "string",       
       "msisdn": "string",      
       "streetAddress" : "string",      
       "coAddress" : "string",          
       "city" : "string",
       "zipCode" : "string",
       "countryCode" : "string"
      },
     "billingAddress" : {                      
       "firstName" : "firstname/compnayname",  
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectNOptional.
payer.nationalIdentifier.socialSecurityNumberstringNOptional.
payer.nationalIdentifier.countryCodestringNOptional.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.

1.2 Use Case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.

Use Cases: Payments

The following use case scenarios (e.g 1.0 Use Case: Regular Payments) will follow the Create Payment Order use case: PayEx Checkout - Merchant onboarding

1.0 Use Case: Regular Payments

A regular payment for single debit transaction.

IntegrationAllowed
PayEx Checkout with CheckinYes
PayEx Checkout without CheckinYes
PayEx Checkout without Checkin. Merchant onboards consumerYes 
FunctionAllowed
RecurringNo
Store cardNo
Operation VerifyNo

The example requests will have specific parameters set to true or false if it's required in the scenario. 

1.1 Create Payment Order

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}

1.2 Create Payment Order Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.

1.3 Create Payment Order Response

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

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

2.0 Use Case: Recurring Payments

Create a recurrenceToken with an initial purchase or verify paymentOrder to enable the recurring scenario. 

IntegrationAllowed
PayEx Checkout with CheckinYes
PayEx Checkout without CheckinYes
PayEx Checkout without Checkin. Merchant onboards consumerYes 
FunctionAllowed
RecurringYes
Store cardNo
Operation VerifyYes

The example requests will have specific parameters set to true or false if it's required in the scenario.

2.1 Create Payment Order with initiating purchase

Set generateRecurrenceToken value to true and a recurrenceToken will be available to retrieve after the completed payment.

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": true,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

2.2 Retrieve Recurrence Token

When the consumer has completed their payment in the initially created payment order, you are able to retrieve the recurrenceToken from the payment order.

Request
GET /psp/paymentorders/<paymentOrderId>/currentpayment HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "menuElementName": "creditcard",
   "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",
       "operation": "Purchase",
       "intent": "Authorization",
       "state": "Ready",
       "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",
       "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" },
       "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
       "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
       "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" },
       "metadata" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": []
}

2.3 Recurring Payment

When you have a recurrence token safely tucked away, you can use this token in a subsequent Recur payment. This will be a server-to-server affair, as we have tied all necessary payment instrument details related to the recurrence token during the initial payment order.

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

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

Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYRecur is always used for recurring payments.
intentstringYThe intent of the payment.
recurrenceTokenstringYThe reccurenceToken to debit.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringYThe user agent of the payer.
languagestringYThe language of the payer.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Recur",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations":  [
      {
      }
  ]
}

3.0 Use Case: Stored Card Payments

A payment order where the consumer stores their card during the payment. As you will notice, this scenario is the same as a regular payment. This is because the choice is on the consumers end to store their card data on their profile, this option will be available for the consumer inside the payment menu. If the consumer chooses to store their card data, the used card data will be shown (masked) and available to use in future payments.

If you allow consumers to store cards on their profile without making any purchase, use operation Verify.

IntegrationAllowed
PayEx Checkout with CheckinYes
PayEx Checkout without CheckinNo
PayEx Checkout without Checkin. Merchant onboards consumerYes 
FunctionAllowed
RecurringNo
Store cardYes
Operation VerifyYes

The example requests will have specific parameters set to true or false if it's required in the scenario.

3.1 Create Payment Order

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

3.2 Stored Card Payment Order

The card data is stored after the payment is completed and if the consumer chose to store their card. Go back to 3.1 Create Payment and perform the same request when the consumer wants to make a new purchase but this time it will be in a simplified manner as their card is stored on their checkout profile. 

Important! Use Operation Purchase when creating a payment order that should debit the consumer as Verify will not debit any amount.

4.0 Use Case: Stored Card and Recurring Combination Payment

A payment order where you allow the consumer to store their card on their profile and you (the merchant) wants to create a recurrence token for recurring payments.

Recurring payments: Set generateRecurrenceToken value to true and a recurrenceToken will be available to retrieve after the completed payment.

Stored Card: The choice to store a card is on the consumers end, this option will be available for the consumer inside the payment menu. If the consumer chooses to store their card data, the card used will be shown (masked) and available to use in future payments after the completed payment.

IntegrationAllowed
PayEx Checkout with CheckinYes
PayEx Checkout without CheckinNo
PayEx Checkout without Checkin. Merchant onboards consumerYes 
FunctionAllowed
RecurringYes
Store cardYes
Operation VerifyYes

The example requests will have specific parameters set to true or false if it's required in the scenario.

4.1 Create Payment Order

Set generateRecurrenceToken value to true

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": true,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

4.2 Recurring Payment

When the consumer has completed their payment in the initially created payment order, you are able to retrieve the recurrenceToken from the payment order.

Request
GET /psp/paymentorders/<paymentOrderId>/currentpayment HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "menuElementName": "creditcard",
   "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",
       "operation": "Purchase",
       "intent": "Authorization",
       "state": "Ready",
       "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",
       "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" },
       "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
       "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
       "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" },
       "metadata" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": []
}

Create a recurring payment

When you have a recurrence token safely tucked away, you can use this token in a subsequent Recur payment. This will be a server-to-server affair, as we have tied all necessary payment instrument details related to the recurrence token during the initial payment order.

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

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

Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYRecur is always used for recurring payments.
intentstringYThe intent of the payment.
recurrenceTokenstringYThe reccurenceToken to debit.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringYThe user agent of the payer.
languagestringYThe language of the payer.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Recur",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations":  [
      {
      }
  ]
}

4.3 Stored Card Payment Order

If the consumer chose to store their card in the previous payment order created in 4.1 Create Payment Order you can create a new payment order and the consumers card will be presented in the payment menu.

Important! Use Operation Purchase when creating a payment order that should debit the consumer as Verify will not debit any amount.
Set generateRecurrenceToken value to false as you've already created a recurrenceToken for the consumer.

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

5.0 Use Case: Multimerchant Stored Card and Recurring Combination Payment

THIS SCENARIO IS ONLY FOR MULTIMERCHANT CUSTOMERS.

In this scenario we will use 3 active merchants. Merchant One, Merchant Two and Merchant Three.

A payment order where you allow the consumer to store their card on their profile that will be available for several merchants and you (the merchant) wants to create a recurrence token for recurring payments.

Recurring payments: Set generateRecurrenceToken value to true and a recurrenceToken will be available to retrieve after the completed payment.

The recurrenceToken generated will only be available for the merchant whom generated it. 

Stored Card: The choice to store a card is on the consumers end, this option will be available for the consumer inside the payment menu. If the consumer chooses to store their card data, the card used will be shown (masked) and available to use in future payments after the completed payment. The stored card will be available for the consumer on Merchant One, Merchant Two and Merchant Three.

IntegrationAllowed
PayEx Checkout with CheckinYes
PayEx Checkout without CheckinNo
PayEx Checkout without Checkin. Merchant onboards consumerYes 
FunctionAllowed
RecurringYes
Store cardYes
Operation VerifyYes

The example requests will have specific parameters set to true or false if it's required in the scenario. 

5.1 Create Payment Order Merchant One

Set generateRecurrenceToken value to true

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": true,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

5.2 Recurring Payment Merchant One

When the consumer has completed their payment in the created payment order from 5.1, you are able to retrieve the recurrenceToken from the payment order. Only available to use by Merchant One.

Request
GET /psp/paymentorders/<paymentOrderId>/currentpayment HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "menuElementName": "creditcard",
   "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",
       "operation": "Purchase",
       "intent": "Authorization",
       "state": "Ready",
       "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",
       "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" },
       "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
       "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
       "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" },
       "metadata" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": []
}

Create a recurring payment for Merchant One

When you have a recurrence token safely tucked away, you can use this token in a subsequent Recur payment. This will be a server-to-server affair, as we have tied all necessary payment instrument details related to the recurrence token during the initial payment order.

Request Merchant One
POST /psp/paymentorders HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

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

Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYRecur is always used for recurring payments.
intentstringYThe intent of the payment.
recurrenceTokenstringYThe reccurenceToken to debit.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringYThe user agent of the payer.
languagestringYThe language of the payer.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Recur",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations":  [
      {
      }
  ]
}

5.3 Stored Card Payment Order Merchant One

If the consumer chose to store their card in the previous payment order created in 5.1 Create Payment Order you can create a new payment order and the consumers card will be presented in the payment menu.

Important! Use Operation Purchase when creating a payment order that should debit the consumer as Verify will not debit any amount.
Set generateRecurrenceToken value to false as you've already created a recurrenceToken for the consumer.

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

5.4 Stored Card Payment Order Merchant Two

Merchant Two wants to create a payment order for the same consumer as Merchant One in 5.1 but doesn't want to create a recurrenceToken as recurring payments isn't needed. The consumer will have their stored card from 5.1 available to use in the payment menu.

Set generateRecurrenceToken value to false

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": false,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

5.5 Stored Card Payment Order Merchant Three

Merchant Three wants to create a payment order for the same consumer as Merchant One in 5.1 and Merchant Two in 5.4 but in addition wants to generate their own recurrenceToken for recurring payments. The consumer will have their stored card from 5.1 available to use in the payment menu.

Set generateRecurrenceToken value to true

Example follows Create PaymentOrder case: PayEx Checkout - Merchant onboarding

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

{
 "paymentorder": {
   "operation": "Purchase",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",                                 
   "language": "sv-SE",
   "generateRecurrenceToken": true,                         
   "disablePaymentMenu": false,                              
   "urls": {
     "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
     "completeUrl": "http://test-dummy.net/payment-completed",
     "cancelUrl": "http://test-dummy.net/payment-canceled",
     "paymentUrl": "http://test-dummy.net/payment",
     "callbackUrl": "http://test-dummy.net/payment-callback",     
     "termsOfServiceUrl": "http://test-dummy.net/termsandconditoons.pdf",
     "logoUrl": "http://test-dummy.net/logo.png"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant1",                                    
     "productCategory": "A123",                                   
     "subsite": "MySubsite",                                       
     "orderReference" : "or-123456"                               
    },
   "payer": {
     "nationalIdentifier": {                                      
       "socialSecurityNumber": "19XXXXXXXXXX",
       "countryCode": "SE"
      },
     "firstName": "string",                      
     "lastName": "string",                 
     "email": "string",      
     "msisdn": "string",                 
     "workPhoneNumber" : "string",                        
     "homePhoneNumber" : "string",                        
     "shippingAddress" : {                    
       "firstName" : "firstname/companyname",
       "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"
       }
    },
   "metadata": {                                          
     "key1": "value1",
     "key2": 2,
     "key3": 3.1,
     "key4": false
    },
   "items": [                                             
    {
     "creditCard": {
       "rejectCreditCards": false,                   
       "rejectDebitCards": false,                    
       "rejectConsumerCards": false,                 
       "rejectCorporateCards": false                 
      }
    },
    {
     "invoice": {
       "feeAmount" : 1900
      }
    },
    {
     "campaignInvoice": {
       "campaignCode" : "Campaign1",
       "feeAmount" : 2900
      }
    },
    {
     "swish": {
       "EnableEcomOnly": false                 
      }
    }
   ]
  }
}
PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYThe operation that the payment order is supposed to perform.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringNThe user agent of the payer.
languagestringYThe language of the payer.
generateRecurrenceTokenbooleanNDetermines if a recurrence token should be generated. A recurrence token is primarily used to enable recurring payments through server-to-server calls. Default value is false
urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
urls.completeUrlstringYThe URI to redirect the payer to once the payment is completed.
urls.cancelUrlstringNThe URI to redirect the payer to if the payment is canceled.
urls.paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
urls.termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. Require https.
urls.logoUrlstringYThe URI to the logo that will be displayed on redirect pages. Require https.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.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.
payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payer.nationalIdentifierobjectYRequired when merchant onboards consumer.
payer.nationalIdentifier.socialSecurityNumberstringYRequired when merchant onboards consumer.
payer.nationalIdentifier.countryCodestringYRequired when merchant onboards consumer.
payer.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.emailstringNOptional (increases chance for challenge flow if not set)
payer.msisdnstringNOptional (increases chance for challenge flow if not set)
payer.homePhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.workPhoneNumberstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.firstNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.lastNamestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.shippingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.firstNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.lastNamestringNOptional (increases chance for challenge flow if not set) If buyer is a company, use only firstName for companyName.
payer.billingAddress.streetAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.coAddressstringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.citystringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.zipCodestringNOptional (increases chance for challenge flow if not set)
payer.billingAddress.countryCodestringNOptional (increases chance for challenge flow if not set)
accountInfoobjectNOptional. If payer is known by merchant and have some kind of registered user then these fields can be set.
accountInfo.accountAgeIndicatorstringNIndicates 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)
accountInfo.accountChangeIndicatorstringNLength 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)
accountInfo.accountPwdChangeIndicatorstringNIndicates 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)
accountInfo.shippingAddressUsageIndicatorstringNIndicates 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)
accountInfo.shippingNameIndicatorstringNIndicates 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)
accountInfo.suspiciousAccountActivitystringNIndicates 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)
accountInfo.addressMatchIndicatorbooleanNAllows the 3DS Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
riskIndicator.deliveryEmailAddressstringNFor electronic delivery, the email address to which the merchandise was delivered.
riskIndicator.deliveryTimeFrameIndicatorstringNIndicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
riskIndicator.preOrderDatestringNFor a pre-ordered purchase. The expected date that the merchandise will be available.
FORMAT: "YYYYMMDD"
riskIndicator.preOrderPurchaseIndicatorstringNIndicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
riskIndicator.shipIndicatorstringNIndicates 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.giftCardPurchasebooleanNtrue if this is a purchase of a gift card.
riskIndicator.reOrderPurchaseIndicatorstringNIndicates 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.
metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
itemsarrayNThe array of items that will affect how the payment is performed.
items.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.
items.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.
items.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.
items.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.
items.invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
items.swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Purchase",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations": [
    {
     "href": "https://ecom.payex.com/paymentorders/123456123412341234123456789012",
     "rel": "redirect-paymentorder",
     "method": "GET",
     "contentType": "application/json"
    },
    {
     "href": "https://ecom.dev.payex.com/paymentmenu/scripts/client/client-paymentmenu.js",
     "rel": "view-paymentorder",
     "method": "GET",
     "contentType": "application/javascript"
    }
  ]
}

5.6 Recurring Payment Merchant Three

When the consumer has completed their payment for Merchant Three in the created payment order from 5.5, you are able to retrieve the recurrenceToken from the payment order. Only available to use by Merchant Three.

Request Merchant Three
GET /psp/paymentorders/<paymentOrderId>/currentpayment HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "menuElementName": "creditcard",
   "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",
       "operation": "Purchase",
       "intent": "Authorization",
       "state": "Ready",
       "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",
       "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" },
       "cancellations": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations" },
       "reversals": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals" },
       "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" },
       "metadata" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": []
}

Create a recurring payment for Merchant Three

When you have a recurrence token safely tucked away, you can use this token in a subsequent Recur payment. This will be a server-to-server affair, as we have tied all necessary payment instrument details related to the recurrence token during the initial payment order.

Request Merchant Three
POST /psp/paymentorders HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
 "paymentorder": {
   "operation": "Recur",
   "intent": "Authorization",
   "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "description": "Test Recurrence",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls": {
     "callbackUrl": "http://test-dummy.net/payment-callback"
    },
   "payeeInfo": {
     "payeeId": "12345678-1234-1234-1234-123456789012",
     "payeeReference": "CD1234",
     "payeeName": "Merchant3",
     "productCategory": "A123",
     "orderReference": "orderRef123",
     "subsite": "MySubsite"       
    }
  }
}

Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
operationstringYRecur is always used for recurring payments.
intentstringYThe intent of the payment.
recurrenceTokenstringYThe reccurenceToken to debit.
currencystringYThe currency of the payment.
amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
descriptionstringYThe description of the payment order.
userAgentstringYThe user agent of the payer.
languagestringYThe language of the payer.
urls.callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
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 name of the payee, usually the name of the merchant.
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.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "paymentorder": {
   "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "created": "2016-09-14T13:21:29.3182115Z",
   "updated": "2016-09-14T13:21:57.6627579Z",
   "state": "Ready",
   "operation": "Recur",
   "intent": "Authorization",
   "currency": "SEK",
   "amount": 1500,
   "vatAmount": 0,
   "remainingCaptureAmount": 1500,
   "remainingCancellationAmount": 1500,
   "remainingReversalAmount": 0,
   "description": "Test Purchase",
   "userAgent": "Mozilla/5.0...",
   "language": "sv-SE",
   "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
   "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
   "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
   "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
   "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
   "items": [
      {
       "creditCard": {
         "cardBrands": [ "Visa", "MasterCard", "Ica", "etc..." ]
        }
      },
      { "invoice": {} },
      { "campaignInvoice": {} },
      { "swish": {} },
      { "vipps": {} }
    ]
  },
 "operations":  [
      {
      }
  ]
}
Created by Patrick Härmälä on 2019/06/03 12:22