Iberpay Simulator

The Iberpay CSM Service comes with a simulator, which is a stub implementation of the Iberpay system that the Iberpay CSM Service interacts with.

The Iberpay Simulator uses the IPF Simulator API. Click here for more information on the Simulator API.

Inbound (creditor) credit transfer features

The simulator request generator implements a subset of the payment initiation functionality provided by the generic IPF Simulator API, which covers the following features:

  • Initiate inbound single payment

  • Load test (specific number of messages at a specific rate)

Triggering a single inbound credit transfer (pacs.008)

The IPF Simulator API allows controlling the simulator using HTTP. To trigger a single inbound credit transfer (pacs.008) message for testing, use the Simulator API’s requestLoad endpoint. For example, using cURL:

curl -X PUT \
  --url http://localhost:55555/sendRequest \
  -H 'Content-Type: application/json' \
  --data '{
  "amount": {
    "amount": "1",
    "currency": "EUR"
  },
  "originatorAccount": {
    "iban": "DE7921000813610123456789",
    "bic": "CHASUS33"
  },
  "beneficiaryAccount": {
    "iban": "GB9121000418450200051332",
    "bic": "ICONGBA1"
  }
}'
For backwards compatibility reasons, the amount value is interpreted as euro cents and does not accept floating point decimals. So to send €1, set amount to 100. The example above will send one euro cent (€0.01)

The JSON payload in --data uses the RequestDetails type. Click here for the complete schema.

Mapping of RequestDetails fields to Iberpay inbound pacs.008

By default, all fields in the inbound pacs.008 are auto-generated. When sending a single request, it is possible to override the auto-generated fields to use predetermined values.

The table below shows how fields of the RequestDetails type map to fields in the pacs.008 that the Iberpay Simulator will send. All other fields are ignored.

Field in RequestDetails Field it modifies in inbound Iberpay pacs.008

amount.amount

  • GrpHdr.TtlIntBkSttlmAmt.value

  • CdtTrfTxInf.IntrBkSttlmAmt

transactionId

CdtTrfTxInf.PmtId.TxId

originatorName

CdtTrfTxInf.Dbtr.Nm

originatorAccount.iban

CdtTrfTxInf.DbtrAcct.Id.IBAN

originatorAccount.bic

CdtTrfTxInf.DbtrAgt.FinInstnId.BICFI

beneficiaryName

CdtTrfTxInf.Cdtr.Nm

beneficiaryAccount.iban

CdtTrfTxInf.CdtrAcct.Id.IBAN

beneficiaryAccount.bic

CdtTrfTxInf.CdtrAgt.FinInstnId.BICFI

remittanceInfo

CdtTrfTxInf.RmtInf.Ustrd

Triggering multiple inbound pacs.008 messages (for load testing)

The Iberpay Simulator also supports the IPF Simulator API’s requestLoad API which allows for the sending of a batch of inbound pacs.008 messages at a specified rate for load testing. This is also controlled using HTTP. For example, using cURL:

curl -H POST \
  --url http://127.0.0.1:55555/requestLoad \
  -H 'Content-Type: application/json' \
  --data '{
	"size": 1000,
	"requestsPerSecond": 100
}'

The example above will send a total of 1000 pacs.008 messages at the rate of 100 per second, meaning that this load test will last 10 seconds.

For long-running tests (e.g. soak tests lasting several hours) it is possible to inquire on the status of the load test using HTTP. For example, using cURL:

curl http://127.0.0.1:55555/requestLoad

This will return a JSON document like this one:

{
  "requestsPerSecond": 100,
  "requestsLeft": 800,
  "cutOffTime": null
}

Which shows the number of requests left to send at the specified rate.

Sending another requestLoad POST will reset the statistics to the most recently requested load.

Triggering pacs.002 confirmation messages

If the Iberpay Simulator receives a pacs.002 message, it will respond with a pacs.002 confirmation message to simulate the final settlement message that would be sent by the scheme.

Outbound (debtor) credit transfer features

The Iberpay Simulator also supports responding to pacs.008 messages with pacs.002 messages with a success or failure response. The default behaviour is to return a pacs.002 message with a GrpSts of ACCP.

Requesting a rejection for an outbound credit transfer

For testing negative scenarios, it is possible to alter the default ACCP behaviour and send a RJCT instead. To do this, the Iberpay Simulator checks the CdtTrfTxInf.Cdtr.Nm field. Set this field to Cd.XXXX where XXXX is an ISO reason code. This will trigger a RJCT response with the requested ISO reason code. For example, setting the creditor name to Cd.AC06 will trigger a RJCT with AC06 as the reason code

Requesting a non-IBP200 error response

To simulate Iberpay returning a non-IBP200 error response in the Status field, set the CdtTrfTxInf.Cdtr.Nm field to Cd.IBPXXX where XXX is one of the valid Iberpay Status codes, e.g.:

  • IBP400

  • IBP450

  • IBP500

Simulating no-reply

To test outbound scenarios where the scheme does not reply, set the CdtTrfTxInf.Cdtr.Nm field to Prtry.9999. This will instruct the Iberpay Simulator to not send any reply.

Support for Status Request (pacs.028)

The Iberpay Simulator will respond to a pacs.028 message with a pacs.002 ACCP message synchronously as per the Iberpay specification.

Delaying Responses

It is possible to delay the responses to messages using the IPF Simulator’s responseConfiguration API. This is also done using HTTP.

To see the current delay response configuration, for example, using cURL:

curl http://127.0.0.1:55555/responseConfiguration

This will return a response like:

[
  {
    "handlerId": "Pacs008Handler",
    "latency": 0
  },
  {
    "handlerId": "Pacs002Handler",
    "latency": 0
  },
  {
    "handlerId": "Pacs028Handler",
    "latency": 0
  }
]
The values are in seconds

To change the latency of a specific handler, use PUT. For example, using cURL:

curl -X PUT \
  --url http://127.0.0.1:55555/responseConfiguration/Pacs008Handler \
  -H "Content-Type: application/json" \
  -d '{"latency":2}'

The above will change the pacs.008 handler’s behaviour to return a pacs.002 response after 2 seconds.

Sending raw messages

Finally, it is possible to send arbitrary XML messages to the Iberpay CSM Service using the Iberpay Simulator. This is done using the IPF Simulator’s sendRawRequest API. For example, using cURL:

curl -X PUT \
  --url http://localhost:55555/sendRawRequest \
  -H 'Content-Type: text/plain' \
  -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Document xmlns="urn:iso:std:iso:20022:tech:xsd:admi.004.001.02"><SysEvtNtfctn><EvtInf><EvtCd>982</EvtCd><EvtParam>20251212152702IPAYESMMXXXAqj1yCdRAz</EvtParam><EvtParam>BROADCAST</EvtParam><EvtParam>QXCBESQ0XXX</EvtParam><EvtParam>Bankia S.A.</EvtParam><EvtParam>AVAILABLE</EvtParam><EvtParam>LTRCORE</EvtParam><EvtTm>2025-12-12T04:27:02.817Z</EvtTm></EvtInf></SysEvtNtfctn></Document>'

The sendRawRequest API will perform the necessary encoding of the input XML into the correct Iberpay-formatted message.

The list of supported messages that can be sent in using sendRawRequest are:

  • pacs.008

  • pacs.002

  • pacs.028

  • camt.056

  • pacs.004

  • camt.029

  • admi.004

  • Iberpay echo request (WS_DISP_ECO)

  • Iberpay participant data load (WS_CARGAENTIDADESSCTINST)

Configuration Reference

The simulator has the following main configuration keys:

Configuration property Description Default value

ipf.csm.iberpay.simulator.http.server.host

The interface where the Iberpay Simulator will listen for requests from Iberpay CSM Service. Set this to 0.0.0.0 to listen on all interfaces

localhost

ipf.csm.iberpay.simulator.http.server.port

The port where the Iberpay simulator will listen for requests from Iberpay CSM Service.

8080

ipf.csm.iberpay.simulator.http.client.host

The hostname where the Iberpay Simulator will send requests to Iberpay CSM Service.

localhost

ipf.csm.iberpay.simulator.http.client.port

The port where the Iberpay Simulator will send requests to Iberpay CSM Service.

8080

ipf.csm.iberpay.simulator.generator.creditor-agent-bic

The default creditor agent BIC that the simulator will use to send requests if one is not specified through RequestDetails for a single request OR if using requestLoad

ICONGBA0