This collection is secured using OAuth 2.0 tokens with a password grant type.
\nThe app must acquire a token by posting a request to https://auth.[domain]/uaa/oauth/token with Basic Authorization and the username and password in the body. The username is the customer's phone number, and the password is their selected PIN. The grant type, client ID, and secret can be supplied upon integration with a specific environment.
\nThe token can be refreshed upon expiry, or a new one acquired if the user is inactive for too long.
\nSubsequent requests to restricted endpoints must contain the supplied token (a JWT), and whether the user is allowed to access the endpoint is determined based on claims inserted into the token upon its creation. For example, a user's token will claim to belong to them using their account ID. Every request to resources that belong to specific accounts will be checked against the account ID claim in the auth token, and if it doesn't match the request is rejected. Although not all JWTs require a signature and can be tampered with, our ones are verified using a non-default algorithm that only accepts it if it is signed with our own signing key.
\nAdditionally, the token is how the front-end knows what the customer ID is so that it can be used in requests such as Get User Info. The app can decode the token and extract the customer ID claim. This allows us to keep personally identifiable information such as the MSISDN out of the request paths, thereby keeping customer information private.
\nSome endpoints require an idempotency key to be applied to the header to prevent duplicate requests.
\nThe header name is Idempotency-Keyand the value can be any locally generated string. Often a customer identifier + time is used. This value is cached over a short timeframe (1 min by default) and if the same value is sent in that timeframe a 429 Too many requests is returned with a problem+json body. For those endpoints with this filter applied a 400 Bad Request is returned with a problem+json if the header is not included.
This is the request that allows access to the rest of the API. The consumer app sends the user's msisdn with a pin that they have entered. The device ID is used to check whether the user has logged in with this device before. If they haven't they will be sent an OTP. Once the password (and OTP if required) have been accepted a token will be returned containing all the claims that will give the app access to the other requests.
\n","urlObject":{"protocol":"https","path":["uaa","oauth","token"],"host":["auth","[domain]"],"query":[{"key":"deviceId","value":"[deviceId]"},{"key":"otp","value":"[otp]"}],"variable":[]}},"response":[{"id":"649a9ab5-98be-4814-81c0-99bbf939bf69","name":"Valid Token","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"password","type":"text"},{"key":"username","value":"[msisdn]","type":"text"},{"key":"password","value":"[pin]","type":"text"},{"key":"scope","value":"consumer_ops","type":"text"}]},"url":{"raw":"https://auth.[domain]/uaa/oauth/token?deviceId=958038","protocol":"https","host":["auth","[domain]"],"path":["uaa","oauth","token"],"query":[{"key":"deviceId","value":"958038"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"access_token\": \"eyJraWQiOiI0YzQ4MGVkZ...hGx8KJa3rIIw\",\r\n \"scope\": \"consumer_ops\",\r\n \"token_type\": \"Bearer\",\r\n \"expires_in\": 300\r\n}"},{"id":"cdc4dff6-e0fb-4027-ad97-01d25bfc0236","name":"Invalid Client","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic hX2NsaWVudF9pZF06W2NhX2NsaWVudF9zZWNyZXRd","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"password","type":"text"},{"key":"username","value":"[msisdn]","type":"text"},{"key":"password","value":"[pin]","type":"text"},{"key":"scope","value":"consumer_ops","type":"text"}]},"url":"https://auth.[domain]/uaa/oauth/token"},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"error\": \"unauthorized_client\"\r\n}"},{"id":"d743214d-1675-4fb3-b4ef-6880a4bd86b8","name":"Invalid Secret","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"password","type":"text"},{"key":"username","value":"[msisdn]","type":"text"},{"key":"password","value":"[pin]","type":"text"},{"key":"scope","value":"consumer_ops","type":"text"}]},"url":{"raw":"https://auth.[domain]/uaa/oauth/token?Authorization=Basic W2NhX2NsaWVudF9pZF06W2NhX2NsaWVudF9zZWN","protocol":"https","host":["auth","[domain]"],"path":["uaa","oauth","token"],"query":[{"key":"Authorization","value":"Basic W2NhX2NsaWVudF9pZF06W2NhX2NsaWVudF9zZWN","type":"text"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"d0c70fcc-80f8-400d-90db-ce3437303a44"},{"name":"Authorization (client credentials)","id":"a966bf71-6f84-402e-b767-f58f9381f081","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"username":"B2B authorization using just a client ID and password instead of logging in with a username and password as well.
\n","urlObject":{"protocol":"https","path":["uaa","oauth","token"],"host":["auth","[domain]"],"query":[],"variable":[]}},"response":[{"id":"1d5a3a30-9ccd-4957-a37f-392e1a3ff207","name":"Valid Client","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"https://auth.[domain]/uaa/oauth/token"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\"access_token\":\"eyJraWQiOiJlZWQ1ZWMyN...190rMJGj4NQuZqY57pluw\",\"scope\":\"consumer_ops\",\"token_type\":\"Bearer\",\"expires_in\":299}"}],"_postman_id":"a966bf71-6f84-402e-b767-f58f9381f081"}],"id":"000dd2ee-f7d3-41ae-a67d-195d5b3cf9ed","_postman_id":"000dd2ee-f7d3-41ae-a67d-195d5b3cf9ed","description":"","auth":{"type":"oauth2","oauth2":{"clientSecret":"This endpoint is used to get user KYC details, including;
\nGets the list of identifier types usable in the customer registration requests.
\n","auth":{"type":"oauth2","oauth2":{"accessTokenUrl":"Registers a new customer, including contact details and msisdn. Most fields are nullable in case the customer hasn't supplied that information, but the phone number is required.
\nMandatory: Call KYC Confirmation to send OTP to users phone. Then request from user and supply in OTP field to validate registration.
\nThese account type codes are mapped to default values based on configuration in the database.
\nUpdates an existing customer registration.
\nThe Know Your Customer API provides the basic requests the app requires to access all of the basic customer information, as the name implies.
\n","auth":{"type":"oauth2","oauth2":{"accessTokenUrl":"This request gets a string representation of a QR code that contains payment information that another user can scan to initiate a payment.
\nThe QR API response strings are used to create one-off codes that allow consumers to quickly share details for performing payments without having to manually give each other account IDs or msisdns.
\nQR codes that we generate follow EMV format specifications.
\nThe merchant payment with QR code request explicitly supports scanning QR codes, as well as the deposit and withdrawal requests in the Integration API. Additionally, because the owner's mobile number is present in the QR code, any request that uses that number to identify the receviever can be initiated by scanning a QR code if the app extracts the required information and injects that into the request.
\n","_postman_id":"0322db8b-e110-4827-94a4-e86fd9e7500b","auth":{"type":"oauth2","oauth2":{"clientSecret":"A header to prevent duplicate requests. See #Idempotency keys in the introduction for information
\n","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"mode\": \"TRANSACTION\",\r\n \"transactionDate\": 1708495434000, // current time in epoch\r\n \"merchantDetails\": {\r\n \"accountId\": \"401\" // merchant biller account\r\n },\r\n \"customerDetails\": {\r\n \"mobileNumber\": \"640000001\"\r\n },\r\n \"transactionDetails\": {\r\n \"transactionAmount\": \"100.00\",\r\n \"currency\": \"NZD\",\r\n \"balanceType\": \"EMONEY\",\r\n \"channel\": \"Bank\",\r\n \"paymentType\": \"C2MW\", // Deposit Type\r\n \"terminalId\": \"API\", // device-id of enduser can use \"API\" when none provided\r\n \"externalReference\": \"100001\" // (OPTIONAL) unique value for lookup\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://{{API Gateway}}/external-partners/v1/general-transaction","description":"Performs a transaction that, based on the transaction details' payment type, transfers money from the customer's account into the merchant's one to allow the customer to purchase goods or services.
\nThis request reads the accept_language header using \"en\" as the default value.
\nThe specified language is used to show errors (e.g. \"insufficient funds\"), notifications (\"You have received funds from...\"), and reference data (biller names, products, etc.) if the appropriate translation has been loaded into the database.
\n