Paytrim API Service (v1)
Changelog — every change to this API, by date.
- Initiate the onboarding process for a merchant
- Verify the current status of the merchant's onboarding
- Look up a company in the national business register before onboarding it
- Fetch the valid signatory combinations for a company
- Get a list of active pricelists
- Retrieve detailed information about a merchant and its structure, like stores, terminals and accounts
- Add a store to a merchant, and update a store or the merchant's contact details
- Retrieve a merchant's card transaction history
Onboarding is asynchronous. add-merchant answers 202 as soon as the request is accepted and the work continues in the background, so the outcome is read from the status endpoint rather than from the response body.
1. GET company-registry-information/{nationalId} [optional]
Skip it if you already know the national id and that the
merchant is not onboarded yet.
404 ................. not in the register, nothing to onboard
200 isOnboarded=true already a merchant, jump to step 6
200 isOnboarded=false continue
2. GET signatory-combinations/{nationalId}
[[A,B],[A,C]] ....... pick ONE combination, send all of its people
[] .................. sole trader: send the owner with
isBeneficialOwner=true instead
3. GET pricelists .......... pick a priceListId [optional]
Skip it if you have the pricelist ids stored already.
4. POST add-merchant ........ signatories + terminals + stores
202 ................. accepted, onboarding is now running
400 ................. fix the request and send it again
5. GET status/{nationalId} . poll until it settles
Pending ............. still working through the steps
Active .............. done
6. GET merchant-information/{nationalId}
the roles, the stores and their terminals. The store ids here are
the ones PATCH store accepts.
7. POST store/{nationalId} add another store
PATCH store/{nationalId}/{storeId} change one store, partially
PATCH {nationalId}/contact-info change email and/or phone
Url: https://api.paytrim.com/Sandbox/
The sandbox answers from fixed in-memory companies, so the same request always gives the same answer and nothing you send is stored. A store you add or patch will not show up in merchant-information afterwards.
Only companies registered in your own country resolve. A Swedish organisation number called with Finnish credentials is not a valid Finnish id, so it answers 400 "Invalid organization number for country X." A valid id for your country that is not a sandbox company answers 404. In production an invalid id answers 400, and a valid id you have no access to answers 403 (except on company-registry-information and signatory-combinations, which do not check access).
Every market has the same five companies, so you can learn the flow once and repeat it per country.
| What it is for | SE | FI | DK | NO |
|---|---|---|---|---|
| Onboarded and running | 5560729146 | 27481932 | 37120456 | 918834729 |
| Onboarded, still mid-process | 5591283402 | 16350275 | 25894316 | 984520190 |
| Ready to be onboarded | 5020786157 | 30817468 | 41068728 | 829103656 |
| Sole trader, no signing combination | 8904062380 | 19274052 | 18936577 | 916502834 |
| Not in the register | 5564831971 | 23369257 | 20443189 | 992741686 |
| Endpoint | Running | Mid-process | Ready | Sole trader | Not in register |
|---|---|---|---|---|---|
company-registry-information | 200, isOnboarded true | 200, true | 200, false | 200, false | 404 |
signatory-combinations | 200, two combinations | 200, one | 200, one | 200, empty list | 404 |
status | 200, Active | 200, Pending | 404 not onboarded | 404 not onboarded | 404 |
merchant-information | 200, two stores with terminals | 200, one store, no terminals | 404 not onboarded | 404 not onboarded | 404 |
add-merchant | 400 already exists | 400 already exists | 202 with a full combination | 202 with isBeneficialOwner | 404 |
POST store | 200 | 200 | 400 not onboarded | 400 not onboarded | 404 |
PATCH store | 200 | 200 | 404 no store | 404 no store | 404 |
PATCH contact-info | 204 | 204 | 400 not onboarded | 400 not onboarded | 404 |
| Send this | Get back |
|---|---|
| Only half of a two-person combination | 400 Signatories are not a valid combination |
| A person who is in no combination | 400 Unknown signatories |
| A sole trader without isBeneficialOwner | 400 Sole trader without beneficial owner |
| An empty or missing terminals list | 400 No terminals supplied |
| Verifone or Seitatech outside SE | 400 Terminal not available in this country |
| A store id that does not belong to the merchant | 404 Store not found |
| A patch with no fields set | 400 Nothing to update |
- Finland and Denmark return signatories without a
nationalId, because those registers do not supply one. ThecompositeKeyis then the only thing that identifies the person, and it is what you send back insignatories. - Verifone and Seitatech are Swedish only. WestPay and SoftPay work in all four markets.
- Amounts are whole units of the merchant's local currency, SEK, NOK, DKK or EUR, and are bucketed into intervals server-side. The same figure therefore means something different in Finland than in Sweden.
GET Sandbox/Merchant/sandbox-cases returns all of the above for your own country, generated from the fixtures themselves.
That surface has its own companies, three per country, and uses your partner's country. A company from another country is not found.
- SE: 5560572850, 8904062380, 5566808134
- FI: 2876543-5, 3145926-0, 2650185-8
- NO: 926483153, 815730291, 970128468
- DK: 32847528, 29164037, 40536175
Every endpoint that takes a company id in the route validates it first: separators are optional, and an id that is invalid for your country answers 400 "Invalid organization number for country X." A valid id that is not a sandbox company answers 404: "Company not found." on the Merchant endpoints and "Company does not exist" on the Transactions endpoints.