{"openapi":"3.0.0","info":{"title":"External authorisation API","version":"1","description":"Transaction authorisation callback API for clients holding customer balances.","contact":{"email":"support@shaype.com","name":"Tech support"}},"x-readme":{"explorer-enabled":false},"servers":[{"url":"localhost/external-balance"}],"tags":[{"name":"Authorisation holds API"},{"name":"Transactions API"}],"paths":{"/holds":{"post":{"tags":["Authorisation holds API"],"summary":"Create a new card authorisation hold","operationId":"authoriseHold","responses":{"200":{"description":"OK"},"470":{"description":"The request contained valid data and was understood by the server, but the server is refusing action due to internal validity, status or limit checks or similar failure of request to the 3rd party necessary to fulfil client request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"500":{"description":"Internal error"}},"description":"Authorise a new card authorisation hold","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hold"},"examples":{"Create hold request":{"value":{"holdId":"1e07aaff-b93d-4e55-9f65-0b10d8923b68","accountId":"afd68d5a-2f3e-4166-97db-d5db72b76fca","cardId":"b373b5da-6917-4c8a-bd77-fd5eb8208774","customerId":"5f7c2d4e-9b1a-4c3e-8d6f-0a2b4c6d8e1f","amount":{"amount":"12.43","currency":"USD"},"merchantDetails":{"merchantId":"111222912956","name":"Hungry Jacks","merchantCategoryCode":"7512","terminalId":"98514750","cardAcceptorLocation":"Hungry Jacks             Pitt   Park SAU","address":{"street":"Pitt   Park S","city":"Sydney","state":"NSW","postcode":"2000","country":"AUS"}}}}}}}},"parameters":[{"schema":{"type":"string","example":"2023-01-30"},"in":"header","name":"Shaype-Version","description":"Version of the API used to format the payload"},{"schema":{"type":"string","example":"ce8a4e1f-d1b4-404c-ad1b-1200426cafec"},"in":"header","name":"Shaype-Trace-Id","description":"Unique identifier for correlation between systems"},{"schema":{"type":"string","example":"638fdb39-4433-43aa-bf31-315cff02eb7d"},"in":"header","name":"Shaype-Idempotency-Key","description":"Unique request identifier"},{"schema":{"type":"string","example":"1985-04-12T23:20:50.52Z"},"in":"header","name":"Shaype-Timestamp","description":"RFC-3339 date and time of request"},{"schema":{"type":"string"},"in":"header","name":"Shaype-Signature","description":"Signature hash of the request body with the shared secret"},{"schema":{"type":"string","example":"d07c4860-a61f-4d3f-8728-cc5fcbab1cb1"},"in":"header","name":"Shaype-Key-Id","description":"Unique identifier of the key used to verify the signature"}]}},"/holds/{holdId}":{"parameters":[{"schema":{"type":"string","format":"uuid"},"name":"holdId","in":"path","required":true}],"patch":{"tags":["Authorisation holds API"],"summary":"Update existing authorisation hold amount","operationId":"updateHoldAmount","responses":{"200":{"description":"OK"},"470":{"description":"The request contained valid data and was understood by the server, but the server is refusing action due to internal validity, status or limit checks or similar failure of request to the 3rd party necessary to fulfil client request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"500":{"description":"Internal error"}},"description":"Update amount of existing card authorisation hold. May be equal to the total hold amount in which case reverses the whole transaction.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/CurrencyAmount"},"customerId":{"type":"string","format":"uuid","description":"Identifier of the customer who owns the card"},"rawExternalProcessorRequest":{"type":"string","description":"Full request body from card processor. Please contact CSM for access to this functionality."}}},"examples":{"Update hold amount request":{"value":{"amount":{"amount":"56.87","currency":"USD"},"customerId":"5f7c2d4e-9b1a-4c3e-8d6f-0a2b4c6d8e1f"}}}}}},"parameters":[{"schema":{"type":"string","example":"2023-01-30"},"in":"header","name":"Shaype-Version","description":"Version of the API used to format the payload"},{"schema":{"type":"string","example":"ce8a4e1f-d1b4-404c-ad1b-1200426cafec"},"in":"header","name":"Shaype-Trace-Id","description":"Unique identifier for correlation between systems"},{"schema":{"type":"string","example":"638fdb39-4433-43aa-bf31-315cff02eb7d"},"in":"header","name":"Shaype-Idempotency-Key","description":"Unique request identifier"},{"schema":{"type":"string","example":"1985-04-12T23:20:50.52Z"},"in":"header","name":"Shaype-Timestamp","description":"RFC-3339 date and time of request"},{"schema":{"type":"string"},"in":"header","name":"Shaype-Signature","description":"Signature hash of the request body with the shared secret"},{"schema":{"type":"string","example":"d07c4860-a61f-4d3f-8728-cc5fcbab1cb1"},"in":"header","name":"Shaype-Key-Id","description":"Unique identifier of the key used to verify the signature"}]}},"/transactions":{"post":{"tags":["Transactions API"],"summary":"Create a new transaction","operationId":"authoriseTransaction","responses":{"200":{"description":"OK"},"470":{"description":"The request contained valid data and was understood by the server, but the server is refusing action due to internal validity, status or limit checks or similar failure of request to the 3rd party necessary to fulfil client request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"500":{"description":"Internal error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"},"examples":{"Create transaction request":{"value":{"transactionId":"1e07aaff-b93d-4e55-9f65-0b10d8923b68","authorisationTransactionType":"OUTBOUND_PAYMENT","accountId":"afd68d5a-2f3e-4166-97db-d5db72b76fca","amount":{"amount":"12.43","currency":"USD"},"counterpartDetails":{"name":"Bruce Wayne","basicAccountNumber":{"accountNumber":"987654321","branchNumber":"110222"}},"description":"Donation","reference":"#1234","account":{"id":"afd68d5a-2f3e-4166-97db-d5db72b76fca","balance":{"amount":"14.35","currency":"AUD"},"holder":{"id":"577b56a3-412d-4e41-be1c-03e31445cf53","type":"GROUP"},"statistics":{"txn_count_last_10m":3,"txn_sum_last_24h":{"amount":"1260.94","currency":"AUD"}}},"customer":{"id":"670ec7a9-5476-448e-a835-e37c9bcc7b93","details":{"dateOfBirth":"2006-07-27","firstName":"Robert","lastName":"Marley","middleName":"Nesta"},"address":{"administrativeRegion":"SA","countryCodeIso":"AUS","line1":"9 Fifth Ave","line2":"Woodville Gardens","postcode":"5012","townOrCity":"Adelaide"},"tenure_days":195},"transactionTimeUtc":"2026-07-27T13:28:34.998Z"}}}}}},"description":"Authorise a new non-scheme (non-card) transaction","parameters":[{"schema":{"type":"string","example":"2023-01-30"},"in":"header","name":"Shaype-Version","description":"Version of the API used to format the payload"},{"schema":{"type":"string","example":"ce8a4e1f-d1b4-404c-ad1b-1200426cafec"},"in":"header","name":"Shaype-Trace-Id","description":"Unique identifier for correlation between systems"},{"schema":{"type":"string","example":"638fdb39-4433-43aa-bf31-315cff02eb7d"},"in":"header","name":"Shaype-Idempotency-Key","description":"Unique request identifier"},{"schema":{"type":"string","example":"1985-04-12T23:20:50.52Z"},"in":"header","name":"Shaype-Timestamp","description":"RFC-3339 date and time of request"},{"schema":{"type":"string"},"in":"header","name":"Shaype-Signature","description":"Signature hash of the request body with the shared secret"},{"schema":{"type":"string","example":"d07c4860-a61f-4d3f-8728-cc5fcbab1cb1"},"in":"header","name":"Shaype-Key-Id","description":"Unique identifier of the key used to verify the signature"}]}}},"components":{"schemas":{"Hold":{"title":"Hold","type":"object","description":"Card authorisation hold","properties":{"holdId":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"cardId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid","description":"Identifier of the customer who owns the card"},"amount":{"$ref":"#/components/schemas/CurrencyAmount"},"merchantDetails":{"$ref":"#/components/schemas/Merchant"},"rawExternalProcessorRequest":{"type":"string","description":"Full request body from card processor. Please contact CSM for access to this functionality."}},"required":["holdId","accountId","amount","cardId"]},"CurrencyAmount":{"title":"CurrencyAmount","type":"object","description":"Transaction amount. Positive when crediting customer account and negative when debiting.","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]},"Transaction":{"title":"Transaction","type":"object","properties":{"transactionId":{"type":"string","format":"uuid"},"authorisationTransactionType":{"type":"string","enum":["BPAY_TRANSFER_OUT","DIRECT_DEBIT_TRANSFER","GENERAL_CREDIT","GENERAL_DEBIT","INBOUND_PAYMENT","OUTBOUND_PAYMENT"]},"accountId":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/CurrencyAmount"},"counterpartDetails":{"$ref":"#/components/schemas/CounterpartDetails"},"description":{"type":"string"},"reference":{"type":"string"},"account":{"$ref":"#/components/schemas/Account"},"customer":{"$ref":"#/components/schemas/Customer"},"transactionTimeUtc":{"type":"string","format":"date-time","description":"DateTime in UTC format when the transaction occurred","example":"2026-07-27T13:28:34.998Z"}},"required":["transactionId","authorisationTransactionType","accountId","amount"]},"Account":{"title":"Account","type":"object","nullable":true,"description":"Account context at the time of the transaction.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the Account the transaction is against"},"balance":{"allOf":[{"$ref":"#/components/schemas/CurrencyAmount"}],"description":"Balance of the Account immediately before this transaction was applied. Money held in stacks is not included"},"holder":{"$ref":"#/components/schemas/AccountHolder"},"statistics":{"$ref":"#/components/schemas/AccountStatistics"}}},"AccountHolder":{"title":"AccountHolder","type":"object","description":"Whoever the Account belongs to","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the account holder — the Customer when type is CUSTOMER, the Group when type is GROUP"},"type":{"type":"string","description":"Type of the account holder. Possible values:\n * **CUSTOMER**: the Account belongs to a single Customer\n * **GROUP**: the Account is a joint account belonging to a Group","enum":["CUSTOMER","GROUP"]}}},"AccountStatistics":{"title":"AccountStatistics","type":"object","description":"Recent activity on the account, excluding this transaction.","properties":{"txn_count_last_10m":{"type":"integer","format":"int32","description":"Number of transactions on the Account in the 10 minutes before this one. Excludes this transaction","example":3},"txn_sum_last_24h":{"allOf":[{"$ref":"#/components/schemas/CurrencyAmount"}],"description":"Total value of transactions on the Account in the 24 hours before this one, in the Account currency. Amounts are summed as magnitudes, so credits and debits both add and direction is not retained. Excludes this transaction"}}},"Customer":{"title":"Customer","type":"object","nullable":true,"description":"Set when the account holder is a customer, or when a group account transaction was triggered by one.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the Customer"},"details":{"$ref":"#/components/schemas/CustomerDetails"},"address":{"$ref":"#/components/schemas/CustomerAddress"},"tenure_days":{"type":"integer","format":"int32","description":"Whole days between the Customer being created and this transaction","example":195}}},"CustomerDetails":{"title":"CustomerDetails","type":"object","properties":{"dateOfBirth":{"type":"string","format":"date","description":"Date of birth of the Customer in ISO format YYYY-MM-DD","example":"2006-07-27"},"firstName":{"type":"string","description":"First name of the Customer"},"lastName":{"type":"string","description":"Last name of the Customer"},"middleName":{"type":"string","description":"Middle name(s) of the Customer"}}},"CustomerAddress":{"title":"CustomerAddress","type":"object","properties":{"administrativeRegion":{"type":"string","description":"State, county, province, or region"},"countryCodeIso":{"type":"string","description":"Country as three letter code as per ISO 3166","example":"AUS"},"line1":{"type":"string","description":"Address line 1"},"line2":{"type":"string","description":"Address line 2"},"postcode":{"type":"string","description":"Post code or ZIP code"},"townOrCity":{"type":"string","description":"City, district, suburb, town, or village"}}},"Response":{"title":"Response","type":"object","properties":{"errorCode":{"type":"string","enum":["REFUSED_MAX_BALANCE_EXCEEDED","REFUSED_NOT_ENOUGH_FUNDS","REFUSED_SENDER_ACCOUNT_NOT_VERIFIED"]},"reason":{"type":"string"}}},"Merchant":{"title":"Merchant","type":"object","properties":{"merchantId":{"type":"string","minLength":1,"maxLength":15,"description":"Identifies the merchant or entity that accepted the card"},"name":{"type":"string","maxLength":40,"description":"Merchant (or ATM owner) name"},"merchantCategoryCode":{"type":"string","minLength":1,"maxLength":4,"description":"The classification (card acceptor business code or merchant category code) of the merchant’s type of business or service"},"terminalId":{"type":"string","minLength":1,"maxLength":8,"description":"Uniquely identifies the terminal which accepted the card"},"cardAcceptorLocation":{"type":"string","minLength":1,"maxLength":101,"description":"Identifies the merchant or entity that accepted the card and their location"},"address":{"$ref":"#/components/schemas/MerchantAddress"}}},"MerchantAddress":{"title":"MerchantAddress","type":"object","properties":{"street":{"type":"string","maxLength":80,"description":"Merchant/ATM street address"},"city":{"type":"string","maxLength":40,"description":"Merchant/ATM city"},"state":{"type":"string","maxLength":3,"description":"Merchant/ATM region code"},"postcode":{"type":"string","maxLength":20,"description":"Merchant/ATM postal code"},"country":{"type":"string","minLength":3,"maxLength":3,"description":"Merchant/ATM ISO 3-alpha country code"}}},"CounterpartDetails":{"title":"CounterpartDetails","type":"object","nullable":true,"properties":{"name":{"type":"string","nullable":true,"description":"Name of the counterpart"},"basicAccountNumber":{"$ref":"#/components/schemas/BasicAccountNumber","nullable":true}}},"BasicAccountNumber":{"title":"BasicAccountNumber","type":"object","properties":{"accountNumber":{"type":"string","description":"Bank account number"},"branchNumber":{"type":"string","description":"Bank branch number (BSB)"}}}},"securitySchemes":{}}}