WERO Payment Initiation API

API Reference

The WERO payment api uses a subset of the available open banking API's. In this chapter only the api's needed for WERO payment initiation are described, furthermore the fields applicable to a WERO payment are marked purple (optional) and orange (mandatory) in the data models.

Payment Status

The following statuses are used to describe the actual state of processing: 

  • Open
  • Authorised
  • SettlementInProcess
  • SettlementCompleted
  • Cancelled
  • Expired
  • Error

In the following picture the possible WERO status are shown in an activity diagram:

WERO Payment Status

Status mapping to Wero

The following table describes the mapping from the Wero payment status(es) to the unified payment status used in the Open Banking Platform. A Wero Single immediate payment consists of a consent, authorization and capture resource, each have an individual status. The combination of those statuses is mapped to a single Payment status in the Open banking solution.

Worldline Wero ConsentWero AuthorizationWero Individual Capture
OpenRequested or Granted  
AuthorisedGrantedGranted 
SettlementInProcessGrantedGrantedAccepted
SettlementCompletedGrantedGrantedSettled
CancelledDenied  
CancelledGrantedRejected 
CancelledGrantedCancelled 
ExpiredTimeOut  
ErrorGrantedFailed 

POST Payments

Endpoint: POST /payments

Base URL:  /xs2a/routingservice/services/ob/pis/v3

This endpoint is used by the Acceptor to initiate a WERO transaction.

  • The purple fields are applicable to WERO.
  • The orange fields are mandatory for a WERO payment.

More details about the fields can be found in the yaml specification.

Data model

Below is a representation of the API request and response structure.

Request 

Legend

  • Purple fields: are applicable to a WERO payment.
  • Orange fields: are mandatory for a WERO payment.
Request (click to enlarge)Response (click to enlarge)
Post payments v3 WeroPayment Response

Example: WERO Single Immediate payment

Request:

Address: https://localhost:8443/xs2a/routingservice/services/ob/pis/v3/payments
    
    HttpMethod: POST
    Headers: {X-Request-ID=27965d49-b27b-38a9-6f7a-2211cb5c0c78, Authorization=Bearer 69eb307c55eb91b4a4144ec8a2d8562d, MessageCreateDateTime=2022-03-22T14:02:13.184Z, Digest=SHA-256=DZ0QKHaRy/MdbWEI62wuE7xJMrfJJBTUWF8irHIHTGw=, Signature=keyId="8D0F688AD3E6C2D4D5FB99FE129F2A2E3B496AF7",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="DK7sQCW56EMXHOw/rdW3RlrtM2U/QL2Hy5g5Fsq+oZ0qspiDerzYL0FRu47EdGWT9qy7n7R3ay6iJHVCUrgFvVXS806E3Clgh5u7+J8/xgUeEPRglA6jeNaLYErKC+xIklJrmpKODDkD407IgA6Y9LhixFisSfawR1pDs2vwOsB1wnujrwBcKFzYf66/pxhW06NZu98VM0pkLm5OFp82G0x4vHfOPAoo46xcSXd/IbQV0DYZewosQIaI5qAclPvmusO9uXDx90uqgDL4E8fLW4yHEaraW7yDlCx54bcraU4ubo+wqDE8NJMKxEVreI/Se9YY73mvAMnOkon1jZHsAQ=="}, Accept=*/*, Content-Type=application/json
    
    Payload: 
    {
    "PaymentProduct": ["WERO"],
    "CommonPaymentData": {
          "RemittanceInformationStructured": {
          "Reference": "12345"
        },
        "RemittanceInformation": "Example payment",
        "Amount": {
            "Amount": "100.00",
            "Currency": "EUR"
        }
    }
}

Response:

ResponseCode: 201
    
    Headers: {X-Request-ID=0e1b8b7d-2438-4bb0-acf5-d68f967c8b25, MessageCreateDateTime=2022-03-22T14:02:13.694Z, Digest=SHA-256=gJNKvdO+dlRlWyevVFfDeEAAJDtmw41A3pQOyNX3K6o=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="NMQImrvrg664n3rBCF9s8fQLvZVH/zPsHfzzxJ671BWz6fvjtn81Arv6TPd8N6/nLLNNjY23YubI33tYDjyEf1vq1wF3vq/gFqmF2s66dxHFy7Gd9mOEdpxc0BYCwpG2ozntRvnrIv2z9SXFlKljc6OT+mqLo+vCB8Gn6frdrwGgZqY6uHOEh3rPvYJ/nWTHQkfxzx/U624wqtuoI8Va4kIXM2pPBCPo4AAq2hFXtj4Okh5vFmRlRiIM9CFgfO+5k1lMC3YzrmE8aB9CyFoJoT3e5pSKNePL+hunGlJG6XPg92Hg/gpS06PyvCtHA5585ONkQv+oNhFdpfdtob1qBQ=="}
    Payload: {
    "CommonPaymentData": {
       "PaymentStatus": "Open",
       "PaymentId": "1282",
       "AspspPaymentId": "0001092688873027"
   },
   "Links": {
       "RedirectUrl": {
           "Href": "https://pay.int.epi.engineering/516ca41d-d47a-468a-9726-8299d69168a9"
       }
    },
    "UseWaitingScreen": false
}

GET Payment Status

Endpoint: GET /payments/{paymentId}/status

This endpoint is used to retrieve the status of a payment.

Data model

Legend

  • Purple fields: are applicable to a WERO payment.
  • Orange fields: are mandatory for a WERO payment.
RequestResponse (click to enlarge)
Payment Status RequestPayment Status Response

Example: WERO payment status

Request:


Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/1282/status
HttpMethod: GET
Headers: {Accept=application/json, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=aa9ec3e7-dc34-f625-2e97-e16644ea1e77, Authorization=Bearer 59519322f1f56db6bd1d23ac0e22cf5015088f085970fb9b461ff2684bc2e96a, MessageCreateDateTime=2024-01-08T12:55:34.630Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="W/6ViHZJ/x0/KM61H7mwCZQp2/3WPax5seqLpCby0BXwgpVoFrSmCu5oHF2pLS2AdHuTiE6qFsBnMkfeGMEDwtqCdY0GZVQGwZ6j9+6zjJHwm21xZ+BmXXH4puRgqxt7DSnOou3SkstzCblf4gSL8MqIyYu7n+eLQlWvjl57t7dNgX0sNTwJE/1GgU/ukDyUoJl4aO1n9ID8EnLDUpXunbZ+1pyCPGbfz5/pDMrJsKZ9l58tLxj7IneU+Mnai8UJEqrQ441ONgYCHF7KoDxu15XA+IY7DnwkA5u/+QN7IY5KpHG3zP19m7jiOimkI6lrqLAc2Ld4iehjNMGve7Ci7w=="}

Response:

    ResponseCode: 200
     
    Headers: {X-Request-ID=3a3df5d3-fa9e-4fee-b9fd-067c23dc91fa, MessageCreateDateTime=2024-01-08T12:55:35.032Z, Digest=SHA-256=pV9HQh/XGpLmawhfj9d/hxYucKkOQCKV9BJ978PeW5k=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="DMvxRTvhRG1kFAy0JPbBzdoRrXq5C9OUJHl6GMQkdNriG4SeuHGaFpdaDA6NgFw2+Ky/RBYiruL18ul+1ZvmdhlyhMaRqR0J7Jg/m9JMyu3wFunBVINysQ+2yj0ucXRMck/CoBW1mYwjDCGCN7xOofw2mZLV6PHjP9xHaDA855iPYE7HUaukB/qveA/S6B2qsjFxDs5AJh6VSWEoknA1+NJZCEX2VC23bnkMgy92qN6bZch5bL3462yFA/0uA75k9XH3O7+Jesl86tBU3kKATNk5n2//vun+Bg4NlSQjU21m6B+nOZT1M+TUkVzG0KWdByf6yFv/x0rp7hifnFZvjA==", Date=Mon, 08 Jan 2024 12:55:35 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "PaymentProductUsed": "WERO",
    "CommonPaymentData": {
        "PaymentStatus": "SettlementCompleted",
        "PaymentId": "1282",
        "AspspPaymentId": "0001092688873027",
        "AspspId": "10002",
        "InitiatingPartyReferenceId": "7cc080484bd74d2c8c1d8d2b296ee5b9"
        }
    }
Enable "on this page" menu on doc section
On