> For the complete documentation index, see [llms.txt](https://experience-digital-transform.gitbook.io/experience-digital-transformation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://experience-digital-transform.gitbook.io/experience-digital-transformation/roadmap/module-4-identity-and-payments/4.5-generating-the-payment-connection.md). # 4.5 Generating the payment connection To pay through the block you configure the sender, the programme, the beneficiary, the payment and the route for its status. {% embed url="" %} Generating the payment connection (\~4 min) {% endembed %} **Watch first (\~4 min).** Then read on: the page carries what the video says, and the AI usage tip. > **Single message.** To pay through the block you configure the sender, the programme, the beneficiary, the payment and the route for its status, and the proof is one test payment whose status comes back. ## The concept Once the Payments block is installed, a service still cannot pay anyone. Five things have to be set up first, and the proof that they work is one small test payment whose status comes back. First, the sender. The block accepts payment requests only from a calling block it has been configured to accept as a source. Second, the programme. Each programme has its payment account and its currency. The specification processes each currency on its own, without conversion, and names currencies by their ISO 4217 codes. So a programme that pays in one currency must pay into accounts held in that same currency. Third, the beneficiary. Before anyone is paid, the service registers each beneficiary in the block's account mapper: a functional identifier, the way of payment, such as a bank account or mobile money, and the financial address where the money goes. The mapper answers on a callback address the service gives it. The service's own register keeps no payment details. In Progressa the functional identifier is the learner's number in the learner register, never the national number. Fourth, the payment. The service hands the block a batch, which may hold one payment or many. The specification sets the least a payment request must contain: the payer's identifier, the payee's identifier, the amount, the currency, the policy, and the sender's own identifier for the transaction. The block gives each payment in the batch an instruction identifier of its own, so that every payment can be followed. Fifth, the route for status. The service gives the block an address to which status is sent, and it can also ask for the status of one payment. A status is success, failed, or in progress. Around all five sits transport and security. The block's interface is published through the Information Mediator, every call travels over a secure connection with an authorisation token, and the messages about a payment are authenticated. The check that proves the connection uses one test beneficiary, one test amount, and a test environment. The beneficiary is registered, and the callback confirms it. A batch of one payment is submitted. The service then asks for the status of that payment. The check passes when the answer is a status, success, failed or in progress, rather than an error, and when the same status arrives at the address configured for it. ![F11. The path of a payment: programme account, Payments block, payer bank, payment system](https://2615884909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR64GcRtMZNpXXmn3HRFt%2Fuploads%2FCWvrdhMgaTcNAulp4N8J%2FF11_payment-path-40fb3826.png?alt=media) {% hint style="info" %} **Demonstration.** A beneficiary registered, a batch of one payment, the status returned. It needs P1 to P7. Until it is recorded, the storyboard in the script stands in its place; see the [build plan](/experience-digital-transformation/roadmap/the-build-plan.md). {% endhint %} ## Your turn โ€” Draft the payment connection for one programme {% hint style="success" %} **๐Ÿ’ก AI usage tip** ยท Draft the payment connection for one programme **Bring:** The description of one payment programme. **Get:** A draft configuration of the source, the programme, the onboarding, the batch and the route for status, with every test value marked. **Time:** \~10โ€“15 min ยท **Assistant:** any; the tips are tool-neutral. **Watch for:** Tests use a test beneficiary, a test amount and a test environment. {% endhint %} **The problem it solves.** An Architect connecting a programme to the Payments block needs a first draft of the five things the connection holds: the accepted source, the programme with its account and currency, the onboarding of a beneficiary, the batch, and the route for status. This prompt drafts them from the description of the programme, using test values only. {% tabs %} {% tab title="Prompt" %} Copy the prompt, replace the bracketed parts with your own context, and run it in the AI assistant of your choice. Never paste personal data or unpublished documents โ€” see [How to use the plays](https://experience-digital-transform.gitbook.io/experience-digital-transformation/government-enterprise-architecture-gea/developing-a-gov-enterprise-architecture-gea/start-here/how-to-use-the-plays). ``` Below is the description of a payment programme in [country X]: [paste โ€” the programme's name, the paying body, its account and currency, who is paid, how often, and the service that will send the payments]. The payments will go through the government's Payments block, which follows the GovStack Payments Building Block specification, Version 3.0 (December 2025). Draft: (1) the calling service configured as an accepted source of payment requests; (2) the programme, with its payment account and its currency as an ISO 4217 code; (3) the onboarding of one test beneficiary into the account mapper โ€” functional identifier, payment modality, financial address โ€” through POST /identityAccountMapper/beneficiary, with the callback address; (4) a bulk payment of one test payment through POST /batchtransactions, containing at least the payer and payee identifiers, the amount, the currency, the policy and the source's transaction identifier; (5) the route for status โ€” the callback address for pushed status, and the status check for one payment through POST /api/v1/batch. Use test values throughout and mark each one [test]. Output: a draft configuration of the source, the programme, the onboarding, the batch and the route for status, with every test value marked. ``` [Open in Claude](https://claude.ai/new?q=Below%20is%20the%20description%20of%20a%20payment%20programme%20in%20%5Bcountry%20X%5D%3A%20%5Bpaste%20%E2%80%94%20the%20programme%27s%20name%2C%20the%20paying%20body%2C%20its%20account%20and%20currency%2C%20who%20is%20paid%2C%20how%20often%2C%20and%20the%20service%20that%20will%20send%20the%20payments%5D.%20The%20payments%20will%20go%20through%20the%20government%27s%20Payments%20block%2C%20which%20follows%20the%20GovStack%20Payments%20Building%20Block%20specification%2C%20Version%203.0%20%28December%202025%29.%20Draft%3A%20%281%29%20the%20calling%20service%20configured%20as%20an%20accepted%20source%20of%20payment%20requests%3B%20%282%29%20the%20programme%2C%20with%20its%20payment%20account%20and%20its%20currency%20as%20an%20ISO%204217%20code%3B%20%283%29%20the%20onboarding%20of%20one%20test%20beneficiary%20into%20the%20account%20mapper%20%E2%80%94%20functional%20identifier%2C%20payment%20modality%2C%20financial%20address%20%E2%80%94%20through%20POST%20%2FidentityAccountMapper%2Fbeneficiary%2C%20with%20the%20callback%20address%3B%20%284%29%20a%20bulk%20payment%20of%20one%20test%20payment%20through%20POST%20%2Fbatchtransactions%2C%20containing%20at%20least%20the%20payer%20and%20payee%20identifiers%2C%20the%20amount%2C%20the%20currency%2C%20the%20policy%20and%20the%20source%27s%20transaction%20identifier%3B%20%285%29%20the%20route%20for%20status%20%E2%80%94%20the%20callback%20address%20for%20pushed%20status%2C%20and%20the%20status%20check%20for%20one%20payment%20through%20POST%20%2Fapi%2Fv1%2Fbatch.%20Use%20test%20values%20throughout%20and%20mark%20each%20one%20%5Btest%5D.%20Output%3A%20a%20draft%20configuration%20of%20the%20source%2C%20the%20programme%2C%20the%20onboarding%2C%20the%20batch%20and%20the%20route%20for%20status%2C%20with%20every%20test%20value%20marked.) *(pre-fills the prompt in a new chat; check the bracketed parts before sending)* *What to bring and what you get are in the box above.* {% endtab %} {% tab title="Example input" %} {% hint style="warning" %} **Draft worked example, 2026-10-04.** Progressa is the fictional country used across these courses. The input below and the output in the next tab were made for this page by running the prompt once; they are shortened, and they have not been checked as the worked examples of the method have. {% endhint %} The bracketed parts of the prompt were replaced with the following: **\[country X]:** Progressa. **\[the programme]:** the Progressa scholarship test programme, the pilot behind the roadmap's scholarship beacon. The paying body is MoEYS. Its account is a test account at the payer bank, which the build will name; the currency is Progressa's own, replaced in tests by the ISO test code. Learners verified in the learner register (PLR) are paid once a term into a bank account. The service that sends the payments is the learner registration service on the Registration block, run by MoEYS. {% endtab %} {% tab title="Example output" %} {% hint style="warning" %} **Draft: model output, shortened and unverified.** Read it with the notes in the next tab, not on its own. {% endhint %} **Draft โ€” not configured, not run** ```yaml source: # accepted source of payment requests service: MoEYS learner registration id: MOEYS-REGISTRATION-TEST # [test] programme: name: Progressa scholarship test programme payer: MoEYS account: programme test account at the payer bank # [test] currency: XTS # [test] ISO 4217 test code onboarding: # POST /identityAccountMapper/beneficiary payeeIdentity: PLR-TEST-000001 # [test] learner number, never the national number paymentModality: "00" # bank account financialAddress: TEST-ACCOUNT-0001 # [test] callback: https://registration.moeys.progressa.test/payments/callback # [test] batch: # POST /batchtransactions payer: MoEYS scholarship test programme # [test] payee: PLR-TEST-000001 # [test] amount: 1.00 # [test] currency: XTS # [test] policy: [confirm] source_transaction_id: MOEYS-TX-000001 # [test] status: pushed_to: https://registration.moeys.progressa.test/payments/status # [test] check_one: POST /api/v1/batch ``` {% endtab %} {% tab title="Reading the output" %} This is the teaching part of the tip. Work through the output the way a chief architect would: what is earned, what is invented, what is missing.
1. The values are test values and agree with the specimen Every identifier, account, amount and address is marked \[test], and they are the same as in the build plan's payment specimen. The beneficiary is keyed on a learner number, so no national number and no real account enters the draft.
2. The policy was left open, rightly The model did not invent a policy identifier and marked it \[confirm]. The specification names the field, but its value comes from the programme's rules, which nobody has written yet. That is a gap in the programme, not in the draft.
3. Check which service sends the payments The draft follows the specimen and names the learner registration service as the source. A scholarship service of its own would be a different source, with its own identifier. Decide this before the beneficiary is onboarded, because the account mapper refuses the same identifier twice from the same source.
{% hint style="danger" %} **Safeguard.** Tests use a test beneficiary, a test amount and a test environment. Never paste a real person's name, account number or mobile number into the prompt, and never point the draft at a live payer bank. {% endhint %} {% endtab %} {% tab title="What next" %} The block's own place on Linkup, which every call here travels through, is set up in [5.1](/experience-digital-transformation/roadmap/module-5-join-the-blocks-and-prove-the-foundation/5.1-what-must-be-in-place-before-the-blocks-can-call-each-other.md). The draft is proved by one test payment whose status comes back, among the [acceptance checks](/experience-digital-transformation/roadmap/module-5-join-the-blocks-and-prove-the-foundation/5.4-the-acceptance-checks-from-set-up-to-proven.md). {% endtab %} {% endtabs %} ## Sources * GovStack Payments Building Block specification, Version 3.0, December 2025 (), sections 4.16, 5.1.14, 5.3.1, 5.4, 6.3, 6.4, 6.11, 6.14, 7.1.1, 7.2.1, 8.1.2, 8.1.4 and 9.1.1 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://experience-digital-transform.gitbook.io/experience-digital-transformation/roadmap/module-4-identity-and-payments/4.5-generating-the-payment-connection.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.