Initiate a payment V1

To present your customers with a payment experience, you need to use the following API 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 triggers 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 an authorization token from your customer's provider.

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 2-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:

customerId - your unique ID for the customer. Required for all payment types.
countryCode - for 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 SEPA payments only.
paymentAttributes - an object containing the required attributes for the payment. This object is required for all payments, with variations in the required fields depending on payment type.

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

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 - 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:

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"
      }
    ]
  }
}

Initiate a payment V1

Get the list of payment providers

Request payment using the chosen provider

Authorize your customer's payment

Get updates on payments

Sequence diagram for initiating a payment