credit-account

bnpl-payment-order

Changelog

 2024-10-30 - Init documenation


 

Introduction

 The bnpl-payment-order API handles payment flows for multiple buy-now-pay-later services, where the customer themselves are available to choose between preferred payment method from a set of preconfigured payment options.
 


1. Bnpl-payment-orders

Get the specified payment order

1.1 Get specific Bnpl-payment-order

Request
GET /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Payment order that has been authorized and with full RemainingAmount left

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

{
 "paymentOrderId": 1234567890,
 "status": "Authorized",
 "authorizationAmount": 1000.00,
 "remainingAmount": 1000.00,
 "currency": "SEK",
 "sellerAuthorizationId": "1234567890",
 "customer": {
   "nationalConsumerIdentifier": {
     "value": "YYYYMMDD-XXXX",
     "countryCode": "SE"
    },
   "email": "example@payex.com",
   "msisdn": "+46701234567"
  },
 "pointOfSale": "My Web Shop",
 "mcc": "1234",
 "restrictToProfiles": [
    {
     "profileName": "BA_PartPayment",
     "subProfiles": [
        {
         "subProfileName": "InstallmentAccount_3"
        }
      ]
    }
  ],
 "operations": [
    {
     "rel": "add-reversal",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"
    },
    {
     "rel": "redirect",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"
    },
    {
     "rel": "cancel-authorize",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"
    },
    {
     "rel": "add-capture",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"
    }
  ]
}

Possible problems

Http status Problem type Description
400 validation occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation 
404 not-found the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist 
500 fatal an unexpected error has occurred 

1.2 Create Bnpl-payment-order

Create a payment order to begin authorization process

Request
POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "authorizationAmount": 1000.00,
 "currency": "SEK",
 "sellerAuthorizationId": "1234567890",
 "customer": {
   "nationalConsumerIdentifier": {
     "value": "YYYYMMDD-XXXX",
     "countryCode": "SE"
    },
   "email": "example@payex.com",
   "msisdn": "+46701234567"
  },
 "pointOfSale": "My Web Shop",
 "mcc": "1234",
 "restrictToProfiles": [
    {
     "profileName": "BA_PartPayment",
     "subProfiles": [
        {
         "subProfileName": "InstallmentAccount_3"
        }
      ]
    }
  ]
}

Request object specification

Property Data typeFormatRequiredDescription
authorizationAmount number Type: double
Max: 100000000
Min: 0 		Yes The authorization amount, can't have more than 2 decimal places
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
Yes  
sellerAuthorizationId string  Yes The seller's unique identifier of the authorize/payment order
customer object   Yes  
   nationalConsumerIdentifier object   Yes  
      value string  No The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
      countryCode string Pattern: SE|NO|DK|FI No The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. [[ISO 3166-1 alpha-2>>https://sv.wikipedia.org/wiki/ISO_3166]]
   email string  Yes Email to the customer
   msisdn string  Yes Phone number to the customer
pointOfSale string  Yes Trade name of the point of sale. Will be displayed to end customer.
mcc string  Yes Merchant Category Code
restrictToProfiles array   No  
   profileName string  Yes Profile identifier
   subProfiles array   No  
      subProfileName string  Yes Sub profile identifier

Newly created payment order with restricted account profiles

Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "paymentOrderId": 1234567890,
 "status": "Created",
 "authorizationAmount": 1000.00,
 "remainingAmount": 0,
 "currency": "SEK",
 "sellerAuthorizationId": "1234567890",
 "customer": {
   "nationalConsumerIdentifier": {
     "value": "YYYYMMDD-XXXX",
     "countryCode": "SE"
    },
   "email": "example@payex.com",
   "msisdn": "\u002B46701234567"
  },
 "pointOfSale": "My Web Shop",
 "mcc": "1234",
 "restrictToProfiles": [
    {
     "profileName": "BA_PartPayment",
     "subProfiles": [
        {
         "subProfileName": "InstallmentAccount_3"
        }
      ]
    }
  ],
 "operations": [
    {
     "rel": "add-reversal",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"
    },
    {
     "rel": "redirect",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"
    },
    {
     "rel": "cancel-authorize",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"
    },
    {
     "rel": "add-capture",
     "method": "POST",
     "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"
    }
  ],
 "@id": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890"
}

Possible problems

Http status Problem type Description
400 validation occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation 
404 not-found the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist 
500 fatal an unexpected error has occurred 

Response object specification

Property Data typeFormatDescription
authorizationAmount number Type: double
Max: 100000000
Min: 0 		The authorization amount, can't have more than 2 decimal places
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
 
sellerAuthorizationId string  The seller's unique identifier of the authorize/payment order
customer object    
   nationalConsumerIdentifier object    
      value string  The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
      countryCode string Pattern: SE|NO|DK|FI The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. [[ISO 3166-1 alpha-2>>https://sv.wikipedia.org/wiki/ISO_3166]]
   email string  Email to the customer
   msisdn string  Phone number to the customer
pointOfSale string  Trade name of the point of sale. Will be displayed to end customer.
mcc string  Merchant Category Code
restrictToProfiles array    
   profileName string  Profile identifier
   subProfiles array    
      subProfileName string  Sub profile identifier
paymentOrderId number Type: int64 PaymentOrderId aka ExternalReservationId
status string 
  • Created
  • Rejected
  • Canceled
  • Failed
  • Authorized
 
remainingAmount number Type: double Remaining amount of the authorize. If amount is zero then the authorize has already been fully used, cancelled or the payment order has not been authorized yet
operations array  List of operations that is possible to perform on the current resource, read more about the [[hypermedia part of the response>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/ledger-api-general-docs/restful-pattern-guideline/#HHyper-mediaresponse]]
@id string  Uri identifier of the current resource

2. Cancel-authorize

2.1 Create Cancel-authorize

This operation is for removing any remaining amount of an already completed authorization. Already captured amount is unaffected.

Request
POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/cancel-authorize HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status Problem type Description
404 not-found the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist 
500 fatal an unexpected error has occurred 

3. Captures

3.1 Create Capture

Perform a capture to solidify the purchase for this payment order. Multiple captures can be done for one payment order as long as we have RemainingAmount left on the order.

Request
POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/captures HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "amount": 1000.00,
 "currency": "SEK",
 "orderLines": [
    {
     "itemDescription": "Phone",
     "amount": 1000.00
    }
  ],
 "sellerTransactionId": "1234567",
 "receiptReference": "Example-receipt-Phone"
}

Request object specification

Property Data typeFormatRequiredDescription
amount number Type: double
Max: 100000000
Min: 0 		Yes The total amount
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
Yes  
orderLines array   Yes  
   itemDescription string Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ Yes Name or description of an individual item in the capture
   amount number Type: double
Max: 100000000
Min: 0 		Yes Price of an individual item in the capture
sellerTransactionId string  Yes  
receiptReference string Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ Yes A receipt reference meaningful for the consumer

Capture example with one item in the order line

Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "captureId": 1234,
 "amount": 1000.00,
 "currency": "SEK",
 "orderLines": [
    {
     "itemDescription": "Phone",
     "amount": 1000.00
    }
  ],
 "sellerTransactionId": "Example-seller-123",
 "receiptReference": "1234567",
 "@id": "https://example.com/capture/1234"
}

Possible problems

Http status Problem type Description
400 validation occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation 
404 not-found the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist 
500 fatal an unexpected error has occurred 

Response object specification

Property Data typeFormatDescription
amount number Type: double
Max: 100000000
Min: 0 		The total amount
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
 
orderLines array    
   itemDescription string Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ Name or description of an individual item in the capture
   amount number Type: double
Max: 100000000
Min: 0 		Price of an individual item in the capture
sellerTransactionId string   
receiptReference string Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ A receipt reference meaningful for the consumer
captureId number Type: int64  
@id string Uri identifier of the current resource 

4. Reversals

4.1 Create Reversal

Can only reverse captures from this payment order

Request
POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/reversals HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "amount": 1000.00,
 "currency": "SEK",
 "sellerTransactionId": "123"
}

Request object specification

Property Data typeFormatRequiredDescription
amount number Type: double
Max: 100000000
Min: 0 		Yes The total amount to reverse
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
Yes  
sellerTransactionId string  Yes  

Reversal of 1000SEK

Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "reversalId": "12345678",
 "amount": 1000.00,
 "currency": "SEK",
 "sellerTransactionId": "123455679"
}

Possible problems

Http status Problem type Description
400 validation occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation 
404 not-found the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist 
500 fatal an unexpected error has occurred 

Response object specification

Property Data typeFormatDescription
amount number Type: double
Max: 100000000
Min: 0 		The total amount to reverse
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
 
sellerTransactionId string   
reversalId string  Identifier of the reversal
uri string   

5. Redirect

5.1 Redirect

While payee is progressing the authorization implementor should start poll the parent resource BnplPaymentOrder for updates

Request
POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/redirect HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "returnUrl": "https://www.landing-page-for-user-after-payment-order.com",
 "redirectOptions": {
   "languageCode": "SV"
  }
}

Request object specification

Property Data typeFormatRequiredDescription
returnUrl string  Yes Url to return the end user to after process is completed or cancelled
redirectOptions object   Yes  
   languageCode string 
  • EN
  • SV
  • NO
  • DA
Yes  

Example response containing redirect info for the chosen payment method

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

{
 "redirectUrl": "https://www.open-chosen-payment-method-example.com",
}

Possible problems

Http status Problem type Description
409 invalid-payment-method unable to redirect before choosing a payment method 
400 validation occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation 

Response object specification

Property Data typeFormatDescription
redirectUrl string  Url to redirect the user to the bnpl page for the user to continue the process

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Response
HTTP/1.1 400 Error
Content-Type: application/problem+json

{
  "Type" : "ledger/{domain}/v1/problems/validation",
  "Title" : "A validation error occurred",
  "Status" : 400,
  "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
  "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
  "Problems" :
      {
        "amount" : [
           "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
         ]
      }
}
Created by Thomas Hedström on 2024/10/30 13:35