Pay By Bank

Initiate a payment V1

To present your customers with a payment experience, use the following requests:

POST pis/providers : To get a list of providers for the country in which the payment is being made.
POST pis/payment/request : To trigger the user journey for your customer to make their payment.
POST pis/payment/authorize : To get an authorization token from your customer's provider.
POST pis/payment/status : To get the current status of your customer's payment.

Get the list of payment providers

To get a list of payment providers in the country where the payment is being made, use POST pisp/providers.

Populate the countryCode field with the two-character ISO code for the country. For example, UK.

Sample request

Curl

curl -X 'POST' \
  'https://base-url/tsapi/v1/pis/providers' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "countryCode": "UK"
}'

Sample response

Json

{
  "data": [
    {
      "id": "3094",
      "code": "starlingbank_oauth_client_gb",
      "name": "Starling",
      "mode": "oauth",
      "status": "active",
      "interactive": true,
      "pispInstruction": "You will be securely redirected to your financial institution to authenticate",
      "logoUrl": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/gb/starlingbank_oauth_client_gb.svg",
      "countryCode": "GB",
      "createdAt": "2018-04-12T14:27:32Z",
      "updatedAt": "2023-07-12T15:33:52Z",
      "identification_codes": [],
      "paymentTemplates": [
        "FPS"
      ]
    },
    {
      "id": "3830",
      "code": "revolut_client_oauth_gb",
      "name": "Revolut",
      "mode": "oauth",
      "status": "active",
      "interactive": false,
      "pispInstruction": "You will be securely redirected to your financial institution to authenticate",
      "logoUrl": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/gb/revolut_gb.svg",
      "countryCode": "GB",
      "createdAt": "2019-04-12T14:06:05Z",
      "updatedAt": "2023-08-30T07:19:06Z",
      "identification_codes": [],
      "paymentTemplates": [
        "FPS",
        "CHAPS",
        "BACS",
        "FPS_STANDING_ORDER",
        "SEPA",
        "SEPA_INSTANT",
        "SWIFT"
      ]
    }
  ]
}

In the response you can see the available providers, along with key information:

code and id : To identify the provider when you need to get consent to connect.
paymentTemplates : To show which payment types can be used with this provider.

Request payment using the chosen provider

To request the payment, send a request to POST aisp/payment/request.

The request is slightly different depending on the region in which the payment is being requested. You can use:

Region Details
Country/region	Real-Time Payments (Instant)	Low-Value Payments	High-Value Payments
UK	Faster Payments	BACS	CHAPS
SEPA	SEPA Instant Credit Transfer	SEPA Credit Transfer	NA

In the body of this request, you must provide the required information to make either a SEPA or any other kind of payment:

Table of payment attributes and payments
Field	Definition	Payment type required
`endToEndId`	A unique identifier that you must generate. This identifier follows the payment throughout the process and can be used for reconciliation and reporting.	Required for all payment types.
`creditorName`	The name of the party being paid.	Required for all payment types.
`description`	A description of the reason for the payment.	Required for all payment types.
`amount`	The amount being paid.	Required for all payment types.
`currencyCode`	The three-character ISO currency code. For example, `EUR` for Euros or GBP for `UK` pounds sterling.	Required for all payment types.
`creditorIban`	The IBAN number for the party being paid.	Required for SEPA
`debtorIban`	The IBAN number for the party making the payment.	Required for SEPA
`creditorSortCode`	The sort code of the party being paid's bank.	Required for UK BACS, CHAPS and UK FPS
`creditorAccountNumber`	The bank account number of the party being paid.	Required for UK BACS, CHAPS and UK FPS
`customerId`	Your unique ID for the customer.	Required for all payment types.
`countryCode`	The country where the access if being requested.	Required for all payment types.
`providerCode`	The unique code for this provider. Returned in the response to `POST pis/providers`.	Required for all payment types.
`payeeDescription`	Your internal description for the payee.	Required for all payment types.
`returnTo`	The URL that the customer is redirected to after they have completed the payment. This URL must be fully qualified and include the full path, as some providers will validate it. Some providers only permit HTTPS redirect URLs.	Required for all payment types.
`templateIdentifier`	The type of payment being made. Either SEPA, FPS, CHAPS, or BACS.	Required for all payment types.
`locale`	The country within the region of payment.	Required for all payment types.
`paymentAttributes`	An object containing the required attributes for the payment.	Required for all payments, with variations in the required fields depending on payment type.

Sample POST /pisp/payment/request SEPA

Json

{
  "data": {
    "customerId": "00ef7b8enca1elA1tm6bmyphhgk3",
    "countryCode": "DE",
    "providerCode": "berliner_sparkasse_oauth_client_de",
    "payeeDescription": "MusicCorpDE",
    "templateIdentifier": "SEPA",
    "returnTo": "https://www.musiccorp.com/pisp_oauth_callback",
    "locale": "de-DE",
    "paymentAttributes": {
      "endToEndId": "20018300321270540",
      "creditorName": "MusicCorp",
      "creditorIban": "DEXXXXXXXXXXXXXXXXXXXX",
      "debtorIban": "DEXXXXXXXXXXXXXXXXXXXX",
      "description": "For goods",
      "amount": "17.99",
      "currencyCode": "EUR",
      "mode": "Normal"
    },
    "connectTemplate": "jpmorgan_musiccorp_v3"
  }
}

Sample request UK FPS. In a BACS or CHAPS payment, only the template_identifier would be different.

Sample request

Json

{
  "data": {
    "customerId": "D310252",
    "countryCode": "GB",
    "providerCode": "barclays_oauth_client_gb",
    "payeeDescription": "barclays PVT 10-25-23",
    "templateIdentifier": "FPS",
    "returnTo": "https://sites.obtest.com/sites/cib",
    "paymentAttributes": {
      "endToEndId": "PISP_1025_PVT_002",
      "creditorName": "John Smith",
      "creditorSortCode": "XXX242",
      "creditorAccountNumber": "XXXXX035",
      "description": "For Goods",
      "amount": "100.00",
      "currencyCode": "GBP"
    }
  }
}

The auth token and payment_id
The response to a successful payment request contains:

paymentId : The payment ID needed to complete the payment. Youy need this ID to complete the payment and get updates on the payment.
redirectUrl : The redirect URL with a value for the authorization token. You need this token to complete the payment.
expiresAt : The time when payment expires.

Sample response - the same for all payment types

Json

{
  "data": {
    "paymentId": "1105048674708230671",
    "expiresAt": "2023-09-21T04:56:43Z",
    "redirectUrl": "https://paymentservices.jpmorgan.com/payments/connect?token=a8a96b6fa3932885be4a46162fd7a0c1579e65a0803e4946a67dae5279dc0c13"
  }
}

Authorize your customer's payment

Now that the payment has been requested, you must enable your customer to authorize their payment.

To authorize a payment, you need to make a request to POST pisp/payment/authorize.

For all payment types, in your request, you must include:

paymentId : The same provider code used to connect to the chosen provider.
authToken : The token provided by the response to POST /pisp/payments/request.

Sample request payload for all payment types

Json

{
  "paymentId": "1105291498426995690",
  "authToken": "a8a96b6fa3932885be4a46162fd7a0c1579e65a0803e4946a67dae5279dc0c13&end_to_end_id=00000002"
}

Sample response - authorized SEPA payment

Json

{
  "data": {
    "id": 1105291498426995700,
    "providerCode": "deutsche_bank_client_de",
    "providerName": "Deutsche Bank",
    "customerId": 1105291496237569000,
    "createdAt": "2023-09-21T12:43:10Z",
    "updatedAt": "2023-09-21T12:44:52Z",
    "status": "accepted",
    "paymentConsentId": 1105291498334721000,
    "templateIdentifier": "SEPA",
    "paymentAttributes": {
      "mode": "Normal",
      "amount": 12.99,
      "debtorIban": "DE75380707240330795600",
      "description": "NETFLIX",
      "creditorIban": "DEXXXXXXXXXXXXXXXXXXXX",
      "creditorName": "NETFLIX",
      "currencyCode": "EUR",
      "endToEndId": 20043855508803784,
      "customerIpAddress": "159.53.64.214"
    },
    "customFields": {},
    "stages": [
      {
        "id": 1105291498368275500,
        "name": "initialize",
        "createdAt": "2023-09-21T12:43:10Z"
      },
      {
        "id": 1105291670938719200,
        "name": "start",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291671400092700,
        "name": "received",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291678303917000,
        "name": "interactive",
        "createdAt": "2023-09-21T12:43:32Z",
        "interactiveHtml": null,
        "interactiveFields_names": [],
        "interactiveRedirect_url": "https://meine.deutsche-bank.de/taf/db/#/authorizepaymentorder?transaction-id=cce9323d-c57e-4e77-9f1e-c394368e4751&psu-id=9503307956&authorization-id=f8190b5f-f0ee-40c7-987d-3aa453e994aa",
        "interactiveFields_options": null
      },
      {
        "id": 1105292279280571400,
        "name": "submission",
        "createdAt": "2023-09-21T12:44:43Z"
      },
      {
        "id": 1105292284808664000,
        "name": "pending",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292288801641500,
        "name": "completed",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292290093487100,
        "name": "finish",
        "createdAt": "2023-09-21T12:44:44Z"
      }
    ]
  }
},
    "customFields": {},
    "stages": [
      {
        "id": 1105291498368275500,
        "name": "initialize",
        "createdAt": "2023-09-21T12:43:10Z"
      },
      {
        "id": 1105291670938719200,
        "name": "start",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291671400092700,
        "name": "received",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291678303917000,
        "name": "interactive",
        "createdAt": "2023-09-21T12:43:32Z",
        "interactiveHtml": null,
        "interactiveFieldsNames": [],
        "interactiveRedirectUrl": "https://meine.deutsche-bank.de/taf/db/#/authorizepaymentorder?transaction-id=cce9323d-c57e-4e77-9f1e-c394368e4751&psu-id=9503307956&authorization-id=f8190b5f-f0ee-40c7-987d-3aa453e994aa",
        "interactiveFieldsOptions": null
      },
      {
        "id": 1105292279280571400,
        "name": "submission",
        "createdAt": "2023-09-21T12:44:43Z"
      },
      {
        "id": 1105292284808664000,
        "name": "pending",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292288801641500,
        "name": "completed",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292290093487100,
        "name": "finish",
        "createdAt": "2023-09-21T12:44:44Z"
      }
    ]
  }
}

Get updates on payments

Now that the payment has been authorized, you can get a status update using POST pisp/payment/status.

In your request you must include:

customerId : Your unique ID provided by J.P. Morgan.
paymentId : The ID of the payment you wish to check on.

Sample request

Json

{
  "customerId": "1105291496237568999",
  "paymentId": "1104531176632095201"
}

The reponse includes:

The details of the payment.
An ID for each stage of the payment process.

Sample response

Json

{
  "data": {
    "id": 1105291498426995700,
    "providerCode": "deutsche_bank_client_de",
    "providerName": "Deutsche Bank",
    "customerId": 1105291496237569000,
    "createdAt": "2023-09-21T12:43:10Z",
    "updatedAt": "2023-09-21T12:44:52Z",
    "status": "accepted",
    "paymentConsentId": 1105291498334721000,
    "templateIdentifier": "SEPA",
    "paymentAttributes": {
      "mode": "Normal",
      "amount": 12.99,
      "debtorIban": "DE75380707240330795600",
      "description": "NETFLIX",
      "creditorIban": "DEXXXXXXXXXXXXXXXXXXXX",
      "creditorName": "NETFLIX",
      "currencyCode": "EUR",
      "endToEndId": 20043855508803784,
      "customerIpAddress": "159.53.64.214"
    },
    "customFields": {},
    "stages": [
      {
        "id": 1105291498368275500,
        "name": "initialize",
        "createdAt": "2023-09-21T12:43:10Z"
      },
      {
        "id": 1105291670938719200,
        "name": "start",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291671400092700,
        "name": "received",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291678303917000,
        "name": "interactive",
        "createdAt": "2023-09-21T12:43:32Z",
        "interactiveHtml": null,
        "interactiveFields_names": [],
        "interactiveRedirect_url": "https://meine.deutsche-bank.de/taf/db/#/authorizepaymentorder?transaction-id=cce9323d-c57e-4e77-9f1e-c394368e4751&psu-id=9503307956&authorization-id=f8190b5f-f0ee-40c7-987d-3aa453e994aa",
        "interactiveFields_options": null
      },
      {
        "id": 1105292279280571400,
        "name": "submission",
        "createdAt": "2023-09-21T12:44:43Z"
      },
      {
        "id": 1105292284808664000,
        "name": "pending",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292288801641500,
        "name": "completed",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292290093487100,
        "name": "finish",
        "createdAt": "2023-09-21T12:44:44Z"
      }
    ]
  }
},
    "custom_fields": {},
    "stages": [
      {
        "id": 1105291498368275500,
        "name": "initialize",
        "createdAt": "2023-09-21T12:43:10Z"
      },
      {
        "id": 1105291670938719200,
        "name": "start",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291671400092700,
        "name": "received",
        "createdAt": "2023-09-21T12:43:31Z"
      },
      {
        "id": 1105291678303917000,
        "name": "interactive",
        "createdAt": "2023-09-21T12:43:32Z",
        "interactiveHtml": null,
        "interactiveFields_names": [],
        "interactiveRedirect_url": "https://meine.deutsche-bank.de/taf/db/#/authorizepaymentorder?transaction-id=cce9323d-c57e-4e77-9f1e-c394368e4751&psu-id=9503307956&authorization-id=f8190b5f-f0ee-40c7-987d-3aa453e994aa",
        "interactiveFields_options": null
      },
      {
        "id": 1105292279280571400,
        "name": "submission",
        "createdAt": "2023-09-21T12:44:43Z"
      },
      {
        "id": 1105292284808664000,
        "name": "pending",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292288801641500,
        "name": "completed",
        "createdAt": "2023-09-21T12:44:44Z"
      },
      {
        "id": 1105292290093487100,
        "name": "finish",
        "createdAt": "2023-09-21T12:44:44Z"
      }
    ]
  }
}

Sequence diagram for initiating a payment

The following sequence diagram illustrates the API workflow for iniriating a payment.