API Technical Overview

The MyBank Gateway API is an HTTP-based REST / JSON API.

The remaining of this section will detail several technical aspects relevant to consuming this API.

API Security

The security layer requires all requests to the MyBank Gateway to be signed using http-signature mechanism as specified by the IETF.
Therefore, as a technical pre-requisite for consuming the MyBank Gateway API, you must have generated a private key and a public X.509 certificate (details will be provided after onboarding). The certificate will then be stored in our API Server.

As we will see in the next section, you will have to add the signature to the headers of your request (X-Signature header) along with the algorithm that has been used to calculate it (X-Signature-Type header) and the thumbprint of the certificate to be used to verify it (X-Thumbprint header).

Below the instructions for the signature method SIGN(Body) which will be referenced in the next section:

1. A SHA256 digest of the HTTP body must be computed.
2. The hash must then be encrypted with the private key of your certificate using the RSA algorithm.

Requests

All requests to the API must be implemented as HTTP POST.

Request Header

The following HTTP Headers must be set for every requests:

Note also that the HTTP Header "user-agent" is not required but, if present, should be limited to max 1024 characters, and HTTP Header "request-id" is not required but, if present, should be limited to max 70 characters.

Request Body

Body content must always be minified when posting requests (no space, no line break).

Example:

{
  "input": {
    "firstName": "John Fitzgerald",
    "lastName": "Smith"
  }
}

must be rendered as follows in the request:

{"input":{"firstName":"John Fitzgerald","lastName":"Smith"}}

Responses

The HTTP status code of the response indicates whether the request could be successfully processed from the technical point of view:

• 200 indicates that the request could be successfully processed from the technical point of view: in this case, the response will include the signature-related headers and a JSON payload as body.
• any other code indicates that the request could NOT be successfully processed from the technical point of view: in this case, no signature-related headers will be provided in the response; the body may only contain a free-text technical message useful to troubleshoot the error.
  Examples:
  • 403 indicates a signature-related error (example: the thumbprint passed in the X-Thumbprint header is unknown, or the signature passed in the X-Signature header is not correct).
  • 500 indicates a permission-related error (example: the certificate used has not been granted the right to call this API).

Response Header

In case of HTTP 200 status code, the API response will include the signature-related headers (X-Signature-Type, X-Thumbprint, X-Signature).

You must ensure you can successfully verify the signature, before you perform any processing on the response.
In order to be able to verify the signature:

• The public MyBank Gateway certificate will be provided to you after onboarding. Your API client's configuration should include this certificate. (In order to allow the graceful renewal of certificates, please structure your configuration so that it is possible to define at least 2 certificates per environment).
• As soon as you receive a response, extract from the X-Thumbprint header the thumbprint of the MyBank Gateway certificate to be used to verify the signature. You will use this information to pick the certificate from your configuration, in case you have more than one.
• Extract the signature from the X-Signature header. The signature has been calculated using the same algorithm that you used to build your request. Verify the signature using the certificate.

Response Body

In case of HTTP 200 status code, the body of the API response will contain a minified JSON payload.

The general structure of this payload is (formatted for readability):

            {
              "output": {
                "result": "string",
                "messages": [
                  {
                    "code": "string",
                    "message": "string",
                    "severity": "string"
                  }
                ],
                "body": {
                  API-specific content
                }
              }
            }

The result attribute indicates whether the request could be successfully processed from the business point of view:

• 200 indicates that the request could be successfully processed from the business point of view, too: in this case, the body attribute will contain valid information.
• any other code indicates that the request could NOT be successfully processed from the business point of view.
  Examples:
  • 400 indicates a request-related error (example: the validity period specified for the payment is too short).
  • 500 indicates a data-related error (example: the payment request specified to initiate a new transaction is expired).