Payment initiation service

Initiate SEPA payment

The following steps are required to initiate a payment

• Create JSON body
• Generate signature and set headers
• Perform request

Create JSON body

This endpoint can be used to create a SEPA payment (regular, urgent/target2(SEPA-NL) or periodic).

Depending on the type of payment being created, fields may be required, optional or forbidden.

¹ none, remittanceInformationUnstructured or remittanceInformationStructured may be submitted, not both.

² EventFrequency7Code: daily is missing from this list because it is not not supported. The value everyFourWeeks is not a part of EventFrequency7Code.

This example contains the minimum amount of information required to initiate a SEPA payment. Please refer to the API DOCUMENTATION page for more information.

{
	"debtorAccount": {
	  "iban": "ACCOUNT_NUMBER"
	},
	"instructedAmount": {
	  "currency": "EUR",
	  "amount": "10.11"
	},
	"creditorAccount": {
	  "iban": "NL91ABNA0417164300"
	},
	"creditorName": "Mr. Test",
	"requestedExecutionDate": "2021-01-25"
}

Generate signature and set headers

Initiate Cross-Border payment

The following steps are required to initiate a Cross-Border Payment

• Create JSON body
• Generate signature and set headers
• Perform request

Create JSON body

This endpoint can be used to create a Cross-Border payment.

Depending on the type of payment being created, fields may be required, optional or forbidden.

This example contains the minimum amount of information required to initiate a SEPA payment. Please refer to the API DOCUMENTATION page for more information.

{
	"debtorAccount": {
		"iban": "ACCOUNT_NUMBER"
	},
	"instructedAmount": {
		"currency": "USD",
		"amount": "10.11"
	},
	"creditorAccount": {
		"bban": "US123456789"
	},
	"chargeBearer": "DEBT",
	"creditorName": "Mr. Test",
	"bankCode": "12345678",
	"contraBankName": "Bank of Amerika",
	"contraBankCity": "New York",
	"contraBankCountryCode": "US",
	"requestedExecutionDate": "2021-01-25"
}

Generate signature and set headers

Initiate bulk payment (SEPA payments)

The following steps are required to initiate a bulk payment

• Create the XML content
• Generate signature and set headers
• Perform request

Create the XML content

This endpoint can be used to create a SEPA bulk payment, an RVR (rijksverrekening/government settlement) bulk payment or a salary bulk payment (note that: urgent/target2(SEPA-NL) bulk payments are no longer supported, use the single sepa-credit-transfers endpoint using the urgent indication instead).

This endpoint supports pain.001.01.03 and pain.001.001.09 XML in the body or using a file stream containing an XML file with pain.001.01.03 XML or pain.001.001.09 or a ZIP file containing a pain.001.01.03 XML or pain.001.001.09 file:

• Using XML in the body:
  To use the body containing the XML, set the header 'Content-Type' to 'application/xml' and add the XML as the body content.
• Using a file stream:
  To use a file stream, set the header 'Content-Type' to 'multipart/form-data' and add the file content as stream to the request. Only 1 file is supported.

This example contains the minimum amount of information required to initiate a bulk payment using pain.001.001.03. Please refer to the API DOCUMENTATION page for more information.

<?xml version="1.0" encoding="utf-8" ?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>137233368626402520</MsgId>
      <CreDtTm>2019-07-01T00:00:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <InitgPty>
        <Nm>Initiating party name</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>SOCRA312575584575543422</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <BtchBookg>true</BtchBookg>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
      </PmtTpInf>
      <ReqdExctnDt>2019-07-01</ReqdExctnDt>
      <Dbtr>
        <Nm>Debtor name</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>ACCOUNT_NUMBER</IBAN>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BIC>NEMONL2G</BIC>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <EndToEndId>12345678</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">10</InstdAmt>
        </Amt>
        <CdtrAgt>
          <FinInstnId>
            <BIC>NEMONL2G</BIC>
          </FinInstnId>
        </CdtrAgt>
        <Cdtr>
          <Nm>Creditor name</Nm>
          <PstlAdr>
            <Ctry>NL</Ctry>
            <AdrLine>Creditor adress</AdrLine>
          </PstlAdr>
        </Cdtr>
        <CdtrAcct>
          <Id>
            <IBAN>NL92NEMO5284338277</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Strd>
            <CdtrRefInf>
              <Tp>
                <CdOrPrtry>
                  <Cd>SCOR</Cd>
                </CdOrPrtry>
                <Issr>CUR</Issr>
              </Tp>
            </CdtrRefInf>
          </Strd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

This example contains the minimum amount of information required to initiate a bulk payment using pain.001.001.09. Please refer to the API DOCUMENTATION page for more information.

<?xml version="1.0" encoding="utf-8" ?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>137233368626402520</MsgId>
      <CreDtTm>2019-07-01T00:00:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <InitgPty>
        <Nm>Initiating party name</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>SOCRA312575584575543422</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <BtchBookg>true</BtchBookg>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
      </PmtTpInf>
      <ReqdExctnDt>
        <Dt>2019-07-01</Dt>
      </ReqdExctnDt>
      <Dbtr>
        <Nm>Debtor name</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>ACCOUNT_NUMBER</IBAN>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BICFI>NEMONL2G</BICFI>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <EndToEndId>12345678</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">10</InstdAmt>
        </Amt>
        <CdtrAgt>
          <FinInstnId>
            <BICFI>NEMONL2G</BICFI>
          </FinInstnId>
        </CdtrAgt>
        <Cdtr>
          <Nm>Creditor name</Nm>
          <PstlAdr>
            <Ctry>NL</Ctry>
            <AdrLine>Creditor adress</AdrLine>
          </PstlAdr>
        </Cdtr>
        <CdtrAcct>
          <Id>
            <IBAN>NL92NEMO5284338277</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>description</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

Generate signature and set headers

Initiate bulk payment (SEPA Direct Debits)

The following steps are required to initiate a bulk payment for SEPA Direct Debits

• Create the XML content
• Generate signature and set headers
• Perform request

Create the XML content

This endpoint can be used to create a SEPA bulk direct debits, an RVR (rijksverrekening/government settlement) bulk direct debit or a NLGOV (overheidsvordering) bulk direct debit.

This endpoint supports pain.008.01.02 and pain.008.001.08 XML in the body or using a file stream containing an XML file with pain.008.01.02 or pain.008.001.08 XML or a ZIP file containing a pain.008.01.02 or pain.008.001.08 XML file:

• Using XML in the body:
  To use the body containing the XML, set the header 'Content-Type' to 'application/xml' and add the XML as the body content.
• Using a file stream:
  To use a file stream, set the header 'Content-Type' to 'multipart/form-data' and add the file content as stream to the request. Only 1 file is supported.

This example contains the minimum amount of information required to initiate a bulk payment (Direct Debit) using pain.008.001.02. Please refer to the API DOCUMENTATION page for more information.

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.008.001.02">
  <CstmrDrctDbtInitn>
    <GrpHdr>
      <MsgId>137233368626402521</MsgId>
      <CreDtTm>2019-07-01T00:00:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <InitgPty>
        <Nm>Initiating party name</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>SOCRA312575584575543423</PmtInfId>
      <PmtMtd>DD</PmtMtd>
      <BtchBookg>true</BtchBookg>
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
        <SeqTp>RCUR</SeqTp>
      </PmtTpInf>
      <ReqdColltnDt>2019-07-01</ReqdColltnDt>
      <Cdtr>
        <Nm>Creditor name</Nm>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <IBAN>ACCOUNT_NUMBER</IBAN>
        </Id>
      </CdtrAcct>
      <CdtrAgt>
        <FinInstnId>
          <BIC>NEMONL2G</BIC>
        </FinInstnId>
      </CdtrAgt>
      <ChrgBr>SLEV</ChrgBr>
      <DrctDbtTxInf>
        <PmtId>
          <EndToEndId>12345678</EndToEndId>
        </PmtId>
        <InstdAmt Ccy="EUR">10</InstdAmt>
        <DrctDbtTx>
          <MndtRltdInf>
            <MndtId>12345678</MndtId>
            <DtOfSgntr>2019-07-01</DtOfSgntr>
          </MndtRltdInf>
          <CdtrSchmeId>
            <Id>
              <PrvtId>
                <Othr>
                  <Id>T</Id>
                </Othr>
              </PrvtId>
            </Id>
          </CdtrSchmeId>
        </DrctDbtTx>
        <DbtrAgt>
          <FinInstnId>
            <BIC>BNGHNL2G</BIC>
          </FinInstnId>
        </DbtrAgt>
        <Dbtr>
          <Nm>Debitor name</Nm>
          <PstlAdr>
            <Ctry>NL</Ctry>
            <AdrLine>Debitor adress</AdrLine>
          </PstlAdr>
        </Dbtr>
        <DbtrAcct>
          <Id>
            <IBAN>NL92NEMO5284338277</IBAN>
          </Id>
        </DbtrAcct>
      </DrctDbtTxInf>
    </PmtInf>
  </CstmrDrctDbtInitn>
</Document>

This example contains the minimum amount of information required to initiate a bulk payment (Direct Debit) using pain.008.001.08. Please refer to the API DOCUMENTATION page for more information.

<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.008.001.08">
  <CstmrDrctDbtInitn>
    <GrpHdr>
      <MsgId>137233368626402521</MsgId>
      <CreDtTm>2019-07-01T00:00:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <InitgPty>
        <Nm>Initiating party name</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>SOCRA312575584575543423</PmtInfId>
      <PmtMtd>DD</PmtMtd>
      <BtchBookg>true</BtchBookg>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>10.00</CtrlSum>
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
        <LclInstrm>
          <Cd>CORE</Cd>
        </LclInstrm>
        <SeqTp>RCUR</SeqTp>
      </PmtTpInf>
      <ReqdColltnDt>2019-07-01</ReqdColltnDt>
      <Cdtr>
        <Nm>Creditor name</Nm>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <IBAN>ACCOUNT_NUMBER</IBAN>
        </Id>
      </CdtrAcct>
      <CdtrAgt>
        <FinInstnId>
          <BICFI>NEMONL2G</BICFI>
        </FinInstnId>
      </CdtrAgt>
      <ChrgBr>SLEV</ChrgBr>
      <DrctDbtTxInf>
        <PmtId>
          <EndToEndId>12345678</EndToEndId>
        </PmtId>
        <InstdAmt Ccy="EUR">10</InstdAmt>
        <DrctDbtTx>
          <MndtRltdInf>
            <MndtId>12345678</MndtId>
            <DtOfSgntr>2019-07-01</DtOfSgntr>
          </MndtRltdInf>
          <CdtrSchmeId>
            <Id>
              <PrvtId>
                <Othr>
                  <Id>T</Id>
                  <SchmeNm>
                    <Prtry>SEPA</Prtry>
                  </SchmeNm>
                </Othr>
              </PrvtId>
            </Id>
          </CdtrSchmeId>
        </DrctDbtTx>
        <DbtrAgt>
          <FinInstnId>
            <BICFI>BNGHNL2G</BICFI>
          </FinInstnId>
        </DbtrAgt>
        <Dbtr>
          <Nm>Debitor name</Nm>
          <PstlAdr>
            <Ctry>NL</Ctry>
            <AdrLine>Debitor adress</AdrLine>
          </PstlAdr>
        </Dbtr>
        <DbtrAcct>
          <Id>
            <IBAN>NL92NEMO5284338277</IBAN>
          </Id>
        </DbtrAcct>
      </DrctDbtTxInf>
    </PmtInf>
  </CstmrDrctDbtInitn>
</Document>

Generate signature and set headers

Save / confirm payment

After a payment or bulk payments have been initiated, it has to be created and confirmed. To do so, the following actions have to be taken:

• Redirect to OAuth2.0 endpoint
• Review payment or process bulk payments
• Save and confirm

Redirect to OAuth2.0 endpoint

Retrieve access token

An access code from the previous step can be exchanged for an access token by the following API

Body

Example of request body. Note: line breaks are for clarifying the example.

client_id=PSDNL-AUT-SANDBOX&
grant_type=authorization_code&
code=f1084fea123e4bc3bcca0a1e5a0a54e5b70e91811dce483aa2168dc539c5f70f&
code_verifier=someverifierdata1234&
state=438b3d36666341019366cf190b57a349&
redirect_uri=redirect_uri

Headers

The following headers are required for the request

Perform request

If the call was successful, a 201 status is returned along with the response body. See below an example of a response.

{
    "access_token": "eyJh...R49Q",
    "token_type": "Bearer",
    "expires_in": "604782",
    "refresh_token": "91f557fe-e01d-4498-bcb9-46dba668de08",
    "scope": "PIS:ec1bff9e-79d2-4588-9112-2ae65ae2a14b"
}

For other possible return codes, see the API DOCUMENTATION page.

Please store access_token somewhere, for example in Notepad, as it is required in later steps. Note that the access token gives access to all API methods for the corresponding paymentInitiationId. In case a paymentInitiationBatchGroupId was used in a redirect, the access token will give access to all paymentInitiationIds that were generated from the bulk payment file, e.g. in a bulk payment file containing multiple bulk-payments/batches.

Retrieve payment status

To retrieve the status of a payment, a payment-id (or paymentInitiationId of the corresponding bulk payment, change the endpoint accordingly e.g. /bulk-payments/pain.001-sepa-credit-transfers or for Cross-Border payment use /payments/cross-border-credit-transfers) as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

Perform request

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
    "transactionStatus": "ACTC"
}

For other possible return codes, see the API DOCUMENTATION page.

Retrieve payment details

To retrieve details of a payment, a payment-id as well as an access_token is required, please see previous steps for directions on how to obtain those. For Cross-Border payment use /payments/cross-border-credit-transfers.

Headers

Perform request

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
    "transactionStatus": "ACTC",
    "debtorAccount": {
      "iban": "NL34BNGT5532530633"
    },
    "instructedAmount": {
      "currency": "EUR",
      "amount": "10.11"
    },
    "creditorAccount": {
      "iban": "NL91ABNA0417164300"
    },
    "CreditorName": "A. Hoogland",
    "creditorAddress": {
      "streetName": "Bernardstraat 12",
      "townName": "Den Haag",
      "postcode": "1234AB",
      "country": "NL"
    },
    "remittanceInformationStructured": {
      "reference": "6000000178319454"
    },
    "requestedExecutionDate": "Mon, 25 Jan 2021 00:00:00 GMT"
}

For other possible return codes, see the API DOCUMENTATION page.

Retrieve bulk payment details

To retrieve details of a bulk payment, a paymentInitiationId of the corresponding bulk payment as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

Perform request

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"transactionStatus": "RCVD",
	"accountNumber": "ACCOUNT_NUMBER",
	"paymentInformationId": "SOCRA312575584575543422",
	"paymentMethod": "TRF",
	"batchBooking": true,
	"numberOfTransactions": 1,
	"totalAmount": 10,
	"requestedExecutionDate": "2019-07-01T00:00:00+02:00",
	"serviceLevelCode": "SEPA"
}

For other possible return codes, see the API DOCUMENTATION page.

Retrieve authorisations

To retrieve authorisations (confirmations) of a payment, a payment-id (or paymentInitiationId of the corresponding bulk payment, change the endpoint accordingly e.g. /bulk-payments/pain.001-sepa-credit-transfers or for Cross-Border payment use /payments/cross-border-credit-transfers) as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

Perform request

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
    "authorisationIds": [
      "19e54cc4-400e-4ba5-a9cd-0bfd39753f64"
    ]
}

Store an authorisation-id somewhere, for example in Notepad, as it is required for the next step.

For other possible return codes, see the API DOCUMENTATION page.

Retrieve authorisation details

To retrieve the details of an authorisation (confirmation) of a payment, a payment-id (or paymentInitiationId of the corresponding bulk payment, change the endpoint accordingly e.g. /bulk-payments/pain.001-sepa-credit-transfers or for Cross-Border payment use /payments/cross-border-credit-transfers) as well as an access_token and an authorisation-id is required, please see previous steps for directions on how to obtain those.

Headers

Perform request

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
    "scaStatus": "finalised"
}

For other possible return codes, see the API DOCUMENTATION page.