Guides

PayTo Staging Testing Suite

Suggest Edits

Preface

  • The goal of this document is to provide a comprehensive guide which enables clients to complete testing of Shaype’s PayTo product (Initiator side) and validate integration of services that make payments possible. A key difference between the PayTo test suite in Shaype's staging environment and Shaype's production environment is that some parts of the process have been replaced by mocks as to not work on actual payments rails and allow for validation of expected API mechanisms. This approach allows for additional steps to be taken when testing in order to simulate the designed flow. Below you can find detailed instructions on how these should be triggered.

Disclaimer: Current mock solution is supported for mandates with 'ad-hoc' frequency. It is recommended to use only this frequency for the moment

Mandate Statuses

  • To create a mandate with a specific status, use the Create Mandate endpoint and input a specific description field status to inform the response type that is returned. Description should follow specific syntax – status:{input status here}. If no status is provided in the description, then mandates for mock solution will be given ‘active’ status. Below you can find list of statuses allowed for mandates with their codes:
    • Created – status:created
    • Active – status:active (no requirement to provide description)
    • Suspended – status:suspended
    • Cancelled – status:cancelled
  • Mandates created this way for mock solution should return a message with the ID of a mandate.

Disclaimer: On production, status changes to mandates should send a notifications to both Initiator and Payer with specific MSCH trigger. To simulate this behaviour use following endpoints while providing described trigger in the request body


Mandate Actions

  • Due to the fact mocks are static, trying to change a mandate status will not actually change it - mocks identify their data based on a pattern in the mandate ID. When triggering a status change action against a mandate, the system will return a message based on the validation that is present in the production environment.

Initiator

1. Create Mandate (Initiator)

  • This step has been described before in the section focusing on mandate statuses. To test a scenario where mandate creation has been rejected, simply create a mandate with the status Created and then use Generate mock Mandate notification for Initiator endpoint with reason code MCRD in trigger field to simulate a notification about mandate creation rejection.
  • Scheduling of a payment is done when information about successful mandate creation is received by the system. To schedule a payment based on a mandate on mocks, simply send notification with MCRC trigger using Generate mock Mandate notification for Initiator

Disclaimer: Mandates with fixed frequency (different than ad-hoc) can be provided with different settings and they will return a generated ID, but only a mocked set of settings will be saved. Trying to read data of such mandate will return predefined saved data.

2. Amend Mandate

  • To amend an Initiator’s data, it is required that the account should be in ACTIVE status and belong to the same account holder. Otherwise, an error will be returned that data validation hasn’t passed.
  • To amend mandate data on Initiator, call Amend Mandate by Initiator API
  • If everything was correct, response should return message about successful amendment. Provided data should be reflected when information about the mandate Creditor is fetched.

3. Amend Payment Terms

  • To amend payment terms as an Initiator, use Amend Mandate payment terms API.
  • If there is an uninitiated scheduled payment for a mandate where payment terms have been amended then that scheduled payment is replaced by a new one which bases its content on new data. For mocks, this doesn’t happen automatically, as this action is triggered by receiving a notification in the system about amendment. To simulate replacement of uninitiated scheduled payment, call the endpoint which sends notification to initiator with MAMC trigger Generate mock Mandate notification for Initiator

4. Suspend Mandate

  • Only mandates that are in ACTIVE status can be successfully suspended, due to status transition flow. Trying to suspend a mandate in other statuses will result in receiving a message: Validation of the request for suspension mandate with id: {mandate_id}: To suspend a mandate it must be in active status.
  • To suspend a mandate, use Suspend Mandate by Initiator API

5. Release Mandate

  • Similarly to mandate suspension, mandates can be released only when suspended. Therefore, trying to release it for any other status than SUSPENDED will result in the return of an error with a message: Validation of the request for releasing mandate with id: {mandate_id} failed. To release a mandate it must be in suspended status.
  • To release a mandate, use Release Mandate by Initiator API

6. Cancel Mandate

  • Mandates can be cancelled from any other status they’re in but canceling a mandate from CREATED status is not done by the Initiator. Therefore, it wasn’t included in the mocks as a scenario available for testing.
  • To test this action, call Cancel Mandate by Initiator API
  • To fail cancelation of a mandate, simply provide an ID of a mandate that doesn’t exist.

7. Recall Mandate Action

  • This endpoint serves to recall a bilateral action which hasn’t been yet confirmed by Payer (is pending). Since mocks are static, this endpoint only shows a response that can be received Resolve Mandate by Initiator
  • Depending on which bilateral action is recalled, specific party should receive a notification with a trigger which indicates what event caused a notification to trigger. Actions which are available for recall right now on production are respectively mandate creation (trigger: MCRR) and bilateral amendment (trigger: MAMR). Current endpoints for notification creation doesn't allow to use this trigger.

Payer

1. Amend Mandate

  • When platform customer takes the role of a Payer in the mandate, then the only thing that is allowed is to amend it to change account from which payment amount is debited during payment realisation. For mocks, the same logic applies to a mandate, and it is possible to change the account using this request. To change account that is set against a mandate, the account that is provided through amend must belong to same account holder of previous account. Also, new account must be in ACTIVE status within the platform for the operation to be valid. In addition to that, the mandate itself must be in either ACTIVE or SUSPENDED status.
  • To change a Payer account, call Amend Mandate by Payer API

2. Suspend Mandate

  • To suspend a mandate use Suspend Mandate by Payer API
  • Only mandates in ACTIVE status can be suspended. Validations for mock solutions are same as production environments and trying to suspend mandate with a status other than ACTIVE will return an error.

3. Release Mandate

  • To release a mandate, call Release Mandate by Payer API
  • Similarly to suspend action, release can be called only for mandates in SUSPENDED status. Doing so for mandates with different status will result in an error, in line with the production environment.

4. Cancel Mandate

Canceling a mandate is done by use of

PATCH/v1/payto/payer/mandates/{mandateId}/cancel

This endpoint works using the same principles as those for cancelation of a mandate from the Initiator’s side.

5. Resolve Mandate Action

  • In production environment, this action is used by Payer to confirm either mandate creation or bilateral amendment of a mandate. Status of a mock mandate is bound to ID pattern, therefore mandate status cannot be changed by this action. Amendment of data on a mandate also happens without confirmation from the Payer, so the endpoint that is used here returns only a fixed response but it can be used on a non-existing mandate to check if expected error is returned. To do so, use Resolve Mandate pending action by Payer endpoint.
  • Do not confuse this endpoint with the one used for mandate action recall, as this one requires query parameter to be added in the URL. To check that, please refer to API documentation.

Payment Statuses

Disclaimer: If no description is provided for a mandate which that allows to recognise status of a payment, then default status 'Settlement aborted' is returned at the moment.

Supported BSBs

  • API to check is BSB enabled for PayTo or not Check if BSB supports PayTo API
  • For the debtor, any BSB can be used when creating a mandate. Using external BSB is advised when simulating a payment to keep data consistency when trying to recreate an external payment.
  • In order to return a not supported response for a BSB, please use the BSB 000 000. 
{  
	"supported": false  
}

Aliases (PayID)

  • When mandate is created, instead of providing account_id to identify creditor or debtor, an alias might be used instead. On production, there are 4 methods that can be used as PayID. It is possible to make a payment on mocks when alias is provided for either Creditor, Debtor or both but it has to be of email payIdType. They can be also used to identify an external account. Below you can find an example of a mandate creation request which involves an alias.

Disclaimer: When creating a mandate on mocks, existing PayId cannot be used. Email alias should follow a specific syntax <bsb><account_number>@something.com

Sample Request - Mandate Create with Alias

{
	"creditorDetails": {
		"accountAliasIdentification": "[email protected]",
		"accountAliasType": "EMAIL_ADDRESS"
	},
	"debtorDetails": {
		"accountAliasIdentification": "[email protected]",
		"accountAliasType": "EMAIL_ADDRESS"
	},
	"description": "orchid Computer",
	"idempotencyKey": "7ade5ae9-e24e-49e3-808e-3f8bd8104a9a",
	"paymentTerms": {
		"amount": {
			"amount": 5,
			"currency": "AUD"
		},
		"frequency": "ADHOC",
		"type": "USAGE_BASED",
		"countPerPeriod": "2"
	},
	"purposeCode": "OTHER",
	"validityEndDate": "2025-01-26",
	"validityStartDate": "2023-08-14"
}

Sample Response - Mandate Create with Alias

{
	"mandateId": "1212f88c-36ad-11ee-bedb-852569012ad8"
}

Test Suite

Assumptions / Prerequisite

  1. Accounts for both debtor and creditor have been previously created in the platform, they have been activated and they should contain money on those accounts
  2. Cuscal configuration must be set up on staging to use external-services-mock (Shaype action)

Ad-hoc end-to-end payment - steps

1. Creating a mandate:

  • To create a mandate, use the Create Mandate endpoint. Successful mandate creation should return its ID as a response. It is important to know that mocks allow for creation of mandates of different payment frequencies and AD-HOC payments, but to test payment flow in later steps, ad-hoc should be input as the frequency.
  • For this request, idempotencyKey must be provided manually and it accepts any UUID.

📘

Notes

  • On production, mandates initially are in status CREATED, but for mock solution they’re always set as ACTIVE unless specified in the mandate description.
  • To test a scenario when payment is successful, provide paymentstatus:safd in the description
{
  "creditorDetails": {
    "accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4"
  },
  "debtorDetails": {
    "accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51"
  },
  "description": "example description",
  "idempotencyKey": "0e374c5b-c2de-45c1-b983-2753610e6ce3",
  "paymentTerms": {
    "amount": {
      "amount": 2.10,
      "currency": "AUD"
    },
    "frequency": "ADHOC",
    "type": "USAGE_BASED",
    "countPerPeriod": "7"
  },
  "purposeCode": "OTHER",
  "validityEndDate": "2024-12-26",
  "validityStartDate": "2023-07-18"
}

2. Triggering notification for mandate authorization:

  • On Shaype's production environment, Cuscal will ask Payer party for a confirmation of mandate authorisation after it is initiated but this step is omitted in staging. Instead, as a next step after confirming the mandate creation as Payer, we can simulate that such authorisation was given but since mock mandates are always in Active status unless specified, then this step is not needed to realise payments via mocks.

3. Triggering ad-hoc payment request for created and authorised mandate

  • When a mandate with ad-hoc frequency is created, to simulate start of payment realisation, Make Adhoc Payment endpoint should be used. When doing so, make payment initiation request (MAPAIN) to the wire mock server. On production, remainder of the payment is realised by Cuscal but mocks require a simulation of this, found in the next steps.
  • Successful MAPAIN for mocks should return payment data with a message that payment has been executed successfully but this response is mocked and should be returned at payment finalisation.

Sample Request - Ad-hoc Payment

{
  "amount": {
    "amount": 2.00,
    "currency": "AUD"
  },
  "idempotencyKey": "0e374c5b-c2de-45c1-b983-2753610e6ce3",
  "description": "description",
  "mandateId": "1212c23a-255c-11ee-9a8e-5d3239591cd9"
}

Sample Response - Ad-hoc Payment

{
  "mandateId": "1212c23a-255c-11ee-9a8e-5d3239591cd9",
  "instructionId": "ANNCAU22XXXI20230718000000000077240",
  "transactionStatus": "SENT",
  "transactionStatusDisplay": "Sent",
  "statusIsFinal": false,
  "message": "Adhoc payment executed successfully."
}

4. Initialisation of resources transfer between accounts - debtor

  • On production, Cuscal sends an instruction to the mandate manager for sending a payment (RAPAIN), which is later carried by it to the payment manager. For mocks, such instruction must be manually triggered by user, by using utility endpoint Generate mock Receive a Payment Instruction (RAPAIN).. Such request should have ACCP transaction status.
  • Later in the process, Cuscal should automatically generate make a payment (MAP) and retract money from debtor account but for mocks, amount is extracted in the same step.
  • To check a debtor’s account, refer to Platform API documentation section on accounts.

Sample Request - Generate mock Receive a Payment Instruction

{
  "creditorInformation": {
    "accountIdentification": "63610027487941",
    "partyName": "JOE BLOGGS"
  },
  "debtorInformation": {
    "accountIdentification": "63610079412687",
    "partyName": "JOHN MAXIMILLIAN DOE"
  },
  "mandateInformation": {
    "initiatingPartyName": "string",
    "mandateIdentification": "1212c23a255c11ee9a8e5d3239591cd9"
  },
  "paymentInformation": {
    "instructedAmount": "2",
    "instructionIdentification": "ANNCAU22XXXI20230718000000000077240",
    "remittanceInformationUnstructured": "This is a payment for invoice number 123456."
  },
  "transactionStatusInformation": {
    "transactionStatus": "ACCP"
  }
}

Sample Response - Generate mock Receive a Payment Instruction

{  
	"message": "Receive A Payment Instruction generated."  
}

📘

Notes

  • MandateIdentification field should include a mandate ID without hyphens
  • InstructedAmount can be different from amount given in ad-hoc payment initialisation
  • instructedAmount will be used for resource extraction but on production it should be the same amount as initial payment amount, and so we advise to do the same.

5. Initialisation of resources transfer between accounts - creditor

  • In the live process, receiving a payment (RAP) is carried out by Cuscal asynchronously from MAP. To simulate a process of receiving a payment and assigning correct amount of resources to creditor’s account, RAP needs to be manually initiated. Use, Generate mock NPP inbound transaction v2 endpoint to do so. A message about successful payment reception should be returned as well.
  • To check creditor’s account, refer to Platform API documentation section on accounts.

Sample Request - Generate mock NPP inbound transaction

{
  "creditorInformation": {
    "accountIdentification": "63610027487941",
    "accountIdentificationTypeCode": "BBAN",
    "ultimatePartyName": "JOE BLOGGS"
  },
  "debtorInformation": {
    "accountIdentification": "63610079412687",
    "accountIdentificationTypeCode": "BBAN",
    "partyName": "JOHN MAXIMILLIAN DOE"
  },
  "initgPtyIdOrgId": "NPBOAU21XXX",
  "mandateInformation": {
    "initiatingPartyName": "string",
    "instructionIdentification": "ANNCAU22XXXI20230718000000000077240",
    "mandateIdentification": "12125151256111ee9a8e4b632ff6f510"
  },
  "paymentId": "ANNCAU22XXX20230718000000000077240",
  "paymentInformation": {
    "categoryPurposeCode": "SALA",
    "endToEndIdentification": "string",
    "instructedAmount": "2",
    "originalMessageIdentification": "ANNCAU22XXX20230718000000000077240",
    "remittanceInformationUnstructured": "This is a payment for invoice number 123456.",
    "transactionIdentification": "ANNCAU22XXXN20230718000000000077240"
  }
}

Sample Response - Generate mock NPP inbound transaction

{  
	"message": "Receive A Payment generated."  
}

📘

Notes

  • For this request, instructionIdentification field should be the same as the ID generated when triggering ad-hoc payment
  • PaymentID and originalMessageIdentification should have the same ID as instructionIdentification but after first part of the ID that indicates Business Identifier Code (BIC - ANNCAU22XXXI2) should be removed
  • OriginalMessageIdentification should contain additional letter N after BIC code

Fixed Schedule end to end payment - steps

  • On the production environment, mandates of frequency different from ADHOC which are in ACTIVE status, have payments based on mandate payment terms scheduled in time. Currently, only the next upcoming payment is scheduled. When the time of the payment comes, scheduled payment is initiated, and another scheduled payment is created in place of the previously existing one that just triggered.
  • For mocks, it is possible to create a mandate with a frequency different to ad-hoc and simulate the process of payment scheduling, but actual transfer of money between accounts is carried out in the same way as ad-hoc payments.

1. Creating non ad-hoc payment

  • Simply call an endpoint to create a mandate. For mock solution there is no real status transition, so a mandate with ACTIVE status should be created for the process. To see how to create mandate with specific status, see the Mandate statuses section.

2. Triggering creation of a scheduled payment initiation request

  • On the production environment, when mandate creation proposal is accepted by the other party, the mandate status is switched to ACTIVE and a new scheduled payment is created. Mock solutions don’t schedule a payment automatically. To create a scheduled payment initiation request for a mandate on mocks, a notification with MCRC trigger should be sent. This way we’re simulating default flow where the mandate that was proposed has been accepted and payment is scheduled right after that fact

3. Transfer of funds between accounts

  • From this point, money transfer looks in the same way as ad-hoc payments. Check step 4 of ad-hoc payments.

Unhappy path scenarios

1. Technical timeout when mandate creation is not accepted by Payer

  • When mandate creation is proposed by Initiator, then action is required by the Payer to accept such a mandate. When no action is taken by Payer, then after 6 days mandate should be automatically rejected and set into CANCELED status by MMS (Mandate Management System). Initiator then receives a notification that the action has expired. To simulate this behaviour, simply create a mandate in CREATED status, then manually trigger a notification to Initiator by using Generate mock Mandate notification for Initiator endpoint with MCRX trigger.

Step 1: Create mandate with CREATED status

Sample Request - Create Mandate

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "status:created", 
	"idempotencyKey": "cabff7ef-2ee5-433b-80bc-bc72cd2125b5", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "MORTGAGE", 
	"validityEndDate": "2025-07-02", 
	"validityStartDate": "2023-07-19" 
}

Sample Response - Create Mandate

{ 
 	"mandateId": "1212c423-262b-11ee-844d-95ee6a0c000c" 
}

Step 2: Get mandate – checking that it has been created properly (optional)

Sample Response - Get Mandate

{
  "mandateId": "1212c423-262b-11ee-844d-95ee6a0c000c",
  "creditorDetails": {
    "accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4",
    "partyReference": "Creditor party reference",
    "partyType": "PERSON",
    "ultimatePartyName": "JOE BLOGGS"
  },
  "debtorDetails": {
    "accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51",
    "accountNumber": "8020016999999",
    "partyName": "JOHN MAXIMILLIAN DOE",
    "partyReference": "Debtor party reference",
    "partyType": "PERSON",
    "ultimatePartyName": "JOHN DOE"
  },
  "description": "Pending-Amend/Port-PMTI/Port-DEBT, Debtor-BBAN, Creditor-BBAN, Payment-Monthly/BALN/Amount/first/last",
  "purposeCode": "RETAIL",
  "registrationDateTime": "2021-02-25T09:25:52.556Z",
  "status": "CREATED",
  "paymentTerms": {
    "amount": {
      "amount": 500.00,
      "currency": "AUD"
    },
    "maximumAmount": {
      "amount": 900.00,
      "currency": "AUD"
    },
    "firstPayment": {
      "amount": {
        "amount": 500.00,
        "currency": "AUD"
      },
      "date": "2020-10-07"
    },
    "lastPayment": {
      "amount": {
        "amount": 900.00,
        "currency": "AUD"
      },
      "date": "2024-10-06"
    },
    "type": "FIXED",
    "frequency": "ADHOC",
    "pointInTime": "09",
    "countPerPeriod": "10"
  },
  "transferArrangement": "Transfer arrangement test",
  "validityStartDate": "2020-10-06",
  "validityEndDate": "2025-05-25"
}

Step 3: Sending MCRX Notification

Sample Request

{
  "trigger": "MCRX",
  "actionDetails": {
    "actionId": "34927ba11a6811ee84e91d8ebf04eef2"
  },
  "mandateDetails": {
    "mandateId": "1212c423262b11ee844d95ee6a0c000c",
    "creditorInformation": {
      "accountIdentification": "63663630855474"
    },
    "debtorInformation": {
      "accountIdentification": "63663672104323"
    },
    "paymentInformation": {
      "amount": "1.00",
      "countPerPeriod": "1",
      "firstPaymentAmount": "2.00",
      "firstPaymentDate": "2023-06-15",
      "lastPaymentAmount": "3.00",
      "lastPaymentDate": "2024-06-15",
      "maximumAmount": "4.00",
      "paymentAmountType": "VARI",
      "paymentFrequency": "DAIL",
      "pointInTime": "10"
    },
    "validityStartDate": "2023-06-15",
    "validityEndDate": "2024-06-15"
  }
}

Sample Response

{ 
 	"message": "Mandate Notification for Initiator generated." 
}

2. Mandate creation is rejected

  • When creating a mandate, there is a possibility that it will be rejected. The mandate can be rejected on Payer’s side or by the system if there is a discrepancy detected. Mocks allow us to simulate what kind of response can be expected on both types of rejection.

1. Mandate creation rejected by Payer

Step 1: Create mandate with CREATED status

Sampel Request - Create Mandate

{
  "creditorDetails": {
    "accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4"
  },
  "debtorDetails": {
    "accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51"
  },
  "description": "status:created",
  "idempotencyKey": "9ecb3732-6a3e-457f-aadc-0c8cc07e66ca",
  "paymentTerms": {
    "amount": {
      "amount": 2.10,
      "currency": "AUD"
    },
    "frequency": "ADHOC",
    "type": "USAGE_BASED",
    "countPerPeriod": "7"
  },
  "purposeCode": "LOAN",
  "validityEndDate": "2023-07-23",
  "validityStartDate": "2023-07-21"
}

Sample Response - Create Mandate 

{ 
	 "mandateId": "12128135-27cb-11ee-80be-e35c1e0c000c" 
}

Step 2: Debtor is rejecting the mandate

  • Use Resolve Mandate pending action by Payer endpoint to simulate a reject action taken by Payer. Make sure to add information in the URL about action resolution, as per the provided request template:

Sample Request

PATCH /v1/payto/payer/mandates/12125940-2ab0-11ee-b219-1515620c000c/resolve?resolution={resolution_value}

Sample Response

{ 
	 "message": "Mandate resolved successfully." 
}

Step 3: Initiator is receiving a notification about mandate being rejected by the debtor

Sample Request

{
  "trigger": "PCRD",
  "actionDetails": {
    "actionId": "34927ba11a6811ee84e91d8ebf04eef2"
  },
  "mandateDetails": {
    "mandateId": "1212813527cb11ee80bee35c1e0c000c",
    "creditorInformation": {
      "accountIdentification": "63663630855474"
    },
    "debtorInformation": {
      "accountIdentification": "63663672104323"
    },
    "paymentInformation": {
      "amount": "1.00",
      "countPerPeriod": "1",
      "firstPaymentAmount": "2.00",
      "firstPaymentDate": "2023-06-15",
      "lastPaymentAmount": "3.00",
      "lastPaymentDate": "2024-06-15",
      "maximumAmount": "4.00",
      "paymentAmountType": "VARI",
      "paymentFrequency": "DAIL",
      "pointInTime": "10"
    },
    "validityStartDate": "2023-06-15",
    "validityEndDate": "2024-06-15"
  }
}

Sample Response

{ 
	 "message": "Mandate Notification for Initiator generated." 
}

2. Mandate creation rejected by the system

  • Mandates can be rejected for various reasons, so only one response has been mocked to show where a reason for rejection can be found. To generate a rejection response by the system, create a mandate while providing mandate_rejected value in the description field.

Mandate Creation Failure

Sample Request

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "mandate_rejected", 
	"idempotencyKey": "4db4d85d-dbff-4a52-9fd7-9e38d5a9949c", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "GOVERNMENT", 
	"validityEndDate": "2023-07-23", 
	"validityStartDate": "2023-07-21" 
}

Sample Response

{ 
 "message": "NOT_FOUND: CUS.API.100522 - Creditor account details incorrect (M900 - No matching record found)", 
 "details": "Please refer to the API documentation or contact Shaype for more info with the traceId.", 
 "status": "422", 
 "traceId": "9b8fa212-d655-487e-bf91-4406957bb584" 
}

3. Payment initiation request (PIR) is initiated but is not proceeding further because time limit of 15 seconds for realisation has passed

  • When a payment is initiated then it is possible to call an endpoint which will check the status of a payment instruction. Depending on phase in which payment instruction is, different statuses could be returned for the production environment. But for mocks, payment is not processed. Therefore to simulate a response from different points in time, mocks return initial status of a payment instruction that should be expected in the response of a created mandate, upon which payment status is based. Then calling for a payment status, it should return a status that is expected to exist at the ending stage of a scenario.

Step 1: Create a mandate with description for time-out scenario

  • To create a mandate for which a payment instruction will return the required statuses, paymentstatus:safd&undv should be provided in the description field of a request using the endpoint

Sample Request

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "paymentstatus:timeout_rjct", 
	"idempotencyKey": "5205b30b-b93a-4a6b-8d87-c5f9ee51df3b", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "GAMBLING", 
	"validityEndDate": "2025-04-15", 
	"validityStartDate": "2023-07-31" 
}

Sample Response

{ 
 	"mandateId": "1212ab33-2fa9-11ee-a1a4-8f2d060a000b" 
}

Step 2 - Make adhoc payment based on a description-controlled mandate

Sample Request

{ 
 "amount": { 
 "amount": 10.00, 
 "currency": "AUD" 
 }, 
 "idempotencyKey": "7627d076-6ca9-4e90-99eb-1ed05dc7ed51", 
 "description": "test", 
 "mandateId": "1212ab33-2fa9-11ee-a1a4-8f2d060a000b" 
}

There will be entry present in the logs:

url: http://external-services-mock/npp/mandates/payments/initiator/v2/ANNCAU22XXX/mandates/1212ab332fa911eea1a48f2d060a000b/instructions/ANNCAU22XXXI20230731000000000078880 
	status: 200 
	decoded content: 
class InlineResponse200 { 
 transactionStatus: RJCT 
 transactionStatusReasonCode: AB01 
}

Response to the request will be received after a 15 second timeout:

{ 
 "mandateId": "1212ab33-2fa9-11ee-a1a4-8f2d060a000b", 
 "instructionId": "ANNCAU22XXXI20230731000000000078880", 
 "transactionStatus": "REJECTED", 
 "transactionStatusDisplay": "Rejected", 
 "statusIsFinal": true, 
 "message": "Adhoc payment executed successfully." 
}

4. Payment request has been sent but is not delivered

Step 1 - Create a mandate with description paymentstatus:sent&undv**

Sample Request

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "paymentstatus:sent&undv", 
	"idempotencyKey": "b31de3dc-dd22-47d3-8996-455cabf79bdf", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "RETAIL", 
	"validityEndDate": "2025-06-21", 
	"validityStartDate": "2023-08-01" 
}

Sample Response

{ 
  "mandateId": "12120aef-3061-11ee-bd98-43435c0a000d" 
}

Step 2 - Make adhoc payment

Sample Request

{ 
 "amount": { 
 "amount": 10.00, 
 "currency": "AUD" 
 }, 
 "idempotencyKey": "79f8a40d-c469-4a4e-b7d8-3e74278c3418", 
 "description": "test", 
 "mandateId": "12120aef-3061-11ee-bd98-43435c0a000d" 
}

Sample Response

 { 
 "mandateId": "12120aef-3061-11ee-bd98-43435c0a000d", 
 "instructionId": "ANNCAU22XXXI20230801000000000079280", 
 "transactionStatus": "SENT", 
 "transactionStatusDisplay": "Sent", 
 "statusIsFinal": false, 
 "message": "Adhoc payment executed successfully." 
}

Step 3 - get mandate payment status

Sample Request

GET /v1/payto/initiator/mandates/112120aef-3061-11ee-bd98-43435c0a000d/instructions/ ANNCAU22XXXI20230801000000000079280/status

Sample Response

{ 
 	"transactionStatus": "UNDELIVERED" 
}


5. Payment request is stored due to participant being unavailable and fails

  • In the same way as the previous case, to simulate this scenario, a mandate with description paymentstatus:safd&undv must be created. SAFD status of a payment informs that payment participant is unavailable and payment has been saved by the system to be processed at a later date. In this scenario, UNDV is returned as a final result after technical retries.

Step 1 - Create a mandate with specified description

Sample Request

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "paymentstatus:safd&undv", 
	"idempotencyKey": "46e9fdd6-af31-4206-98e0-afbb4693f94c", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "LOAN", 
	"validityEndDate": "2024-10-04", 
	"validityStartDate": "2023-08-01" 
}

Sample Response

{ 
 "mandateId": "1212de1e-3061-11ee-bd98-49ab2e0a000c" 
}

Step 2 - Make adhoc payment

Sample Request

{ 
 "amount": { 
 "amount": 10.00, 
 "currency": "AUD" 
 }, 
 "idempotencyKey": "43cf8d84-d9dd-44e6-bd56-5a6cf557b68e", 
 "description": "test", 
 "mandateId": "1212de1e-3061-11ee-bd98-49ab2e0a000c" 
}

Sample Response

{ 
 "mandateId": "1212de1e-3061-11ee-bd98-49ab2e0a000c", 
 "instructionId": "ANNCAU22XXXI20230801000000000079270", 
 "transactionStatus": "STORE_AND_FORWARD", 
 "transactionStatusDisplay": "Store & Forward", 
 "statusIsFinal": false, 
 "message": "Adhoc payment executed successfully." 
}

Step 3 - get mandate payment status

Sample Request

GET /v1/payto/initiator/mandates/1212de1e-3061-11ee-bd98-49ab2e0a000c/instructions/ ANNCAU22XXXI20230801000000000079270/status

Sample Response

{ 
 "transactionStatus": "UNDELIVERED" 
}

6. Payment instruction has been accepted and is in pending status, but is finally rejected

Step 1: Create a mandate with description paymentstatus:recv&rjct

Sample Request

{ 
	"creditorDetails": { 
		"accountId": "596fb54d-2b88-4245-a793-08a5f7a6d6d4" 
	}, 
	"debtorDetails": { 
		"accountId": "fd33a68c-4fc2-4cfa-a16a-e65d9709ac51" 
	},  
	"description": "paymentstatus:recv&rjct", 
	"idempotencyKey": "4cff79d5-c026-4cb1-835f-13c34795f1ea", 
	"paymentTerms": { 
		"amount": { 
			"amount": 2.10, 
			"currency": "AUD" 
		}, 
		"frequency": "ADHOC", 
		"type": "USAGE_BASED", 
		"countPerPeriod": "7" 
	}, 
	"purposeCode": "MORTGAGE", 
	"validityEndDate": "2025-05-21", 
	"validityStartDate": "2023-08-01" 
}

Sample Response

{ 
 "mandateId": "12120260-3061-11ee-bd98-977d250a000e" 
}

Step 2 - Make adhoc payment

Sample Request

{ 
 "amount": { 
 "amount": 10.00, 
 "currency": "AUD" 
 }, 
 "idempotencyKey": "095e17b0-8adb-4c10-be96-468fed71de9a", 
 "description": "test", 
 "mandateId": "12120260-3061-11ee-bd98-977d250a000e" 
} 

Response: 
{ 
 "mandateId": "12120260-3061-11ee-bd98-977d250a000e", 
 "instructionId": "ANNCAU22XXXI20230801000000000079290", 
 "transactionStatus": "RECEIVED", 
 "transactionStatusDisplay": "Received", 
 "statusIsFinal": false, 
 "message": "Adhoc payment executed successfully." 
}

Step 3 - get mandate payment status

Sample Request

GET /v1/payto/initiator/mandates/112120260-3061-11ee-bd98-977d250a000e/instructions/ ANNCAU22XXXI20230801000000000079290/status

Sample Response

{ 
 "transactionStatus": "REJECTED" 
}

Testing end-to-end identification of a payment

  • Platform has means to provide an 'end-to-end' identification of a payment. This identification depends on type of a payment, which is determined by frequency of a mandate. On production, for ad-hoc payments when payment request endpoint is called, it allows to provide a string which limited from 1 to 35 characters. For payments which are scheduled based on mandate frequency (non ad-hoc) then this identification is automatically filled for scheduled payments by information stored within partyReference provided when mandate is created.
  • This identification information is optional. When it is not provided, then system will assume value 'Not provided' in both cases of frequencies for mandates.
  • Mocks allow to test this for ad-hoc mandates. To do so, you need to do following steps:

Ad-hoc mandates

Step 1 - create an ad-hoc mandate

Sample Request

{
	"creditorDetails": {
		"accountId": "0ee7980e-6df9-4d3c-b01b-2fe9d369de07"
	},
	"debtorDetails": {
		"accountId": "d11ad058-e12b-4e02-81fd-ba306663b601"
	},
	"description": "salmon Table",
	"idempotencyKey": "2c4bfa27-7dd6-407d-9d2d-13fec379c94a",
	"paymentTerms": {
		"maximumAmount": {
			"amount": 5,
			"currency": "AUD"
		},
		"frequency": "ADHOC",
		"type": "USAGE_BASED",
		"countPerPeriod": "2"
	},
	"purposeCode": "UTILITY",
	"validityEndDate": "2025-05-27",
	"validityStartDate": "2023-11-29"
}

Sample Response

{
	"mandateId": "12120428-8eb3-11ee-8d7c-c9dd305f4280"
}

Step 2 - make ad-hoc payment

Sample Request

{
	"amount": {
		"amount": 1.28,
		"currency": "AUD"
	},
	"idempotencyKey": "4688ec46-e862-4a87-98f9-a323a81322e7",
	"description": "salmon Table",
	"endToEndId": "NET-1724",
	"mandateId": "12120428-8eb3-11ee-8d7c-c9dd305f4280"
}

Sample Response

{
	"mandateId": "12120428-8eb3-11ee-8d7c-c9dd305f4280",
	"instructionId": "ANNCAU22XXXI20231129000000000093410",
	"transactionStatus": "SENT",
	"transactionStatusDisplay": "Sent",
	"statusIsFinal": false,
	"message": "Adhoc payment executed successfully."
}

Step 3 - Create stub for search payment instructions for a mandate

Sample Request

{
	"mandateIdentification": "121204288eb311ee8d7cc9dd305f4280",
	"paymentInstructionSummaries": [
		{
			"creationDateTime": "2023-11-29T12:33:59.833Z",
			"instructedAmount": 1.28,
			"instructionIdentification": "ANNCAU22XXXI20231129000000000093410",
			"transactionStatus": "RECV",
			"transactionStatusReasonCode": "AB01"
		}
	]
}

Sample Response

{
	"message": "Stub mapping for search payment instruction request created."
}

Step 4 - Search payment instructions by Mandate ID

Sample Request

GET/v1/payto/initiator/mandates/{mandateId}/search

Sample Response

{
	"paymentInstructions": [
		{
			"id": "ANNCAU22XXXI20231129000000000093410",
			"amount": 1.28,
			"creationDateTime": "2023-11-29T12:33:59.833Z",
			"transactionStatus": "RECEIVED",
			"transactionStatusReasonCode": "AB01",
			"endToEndId": "NET-1724"
		}
	]
}

Updated 2 months ago