Gini Merchant API Documentation v1.0

Introduction

Our payment API ensures an exact payment data delivery on the users' side, precisely to their banking app, enabling a smooth bank transfer experience.

We differentiate different use cases where the end-user faces A2A payments. First, if it is BNPL or immediate payment during check-out, and second, if the user is shopping using a mobile app, mobile website or on a browser on a laptop.

As described in this documentation, our QR-Code solution is for users shopping on their laptops/desktops in a BNPL scenario. A future version of this product will also contain a secured payment confirmation, enabling immediate payment use cases embedded in the check-out process.

This API enables the generation of a QR-Code that can be read by the user's banking app to prefill the SEPA transfer form automatically, which avoids manual copy & and pasting or typing and ensures perfect data quality.

Retrieving an instant payment confirmation will also be possible in an upcoming version.

Powered by Gini Pay Connect, we enable a direct connection between a merchant App and a Banking App with a deep link. This API allows the retrieval of available service providers during execution so that users can always get the latest list of bank partners added to our partners' network. All items of this list (bank partners) will be dynamically proofed by our merchant SDK so that only those bank partners that are also installed on the device (smartphone) of the user are shown within the payment options at the mobile merchant checkout.

Getting started

Welcome! In order to interact with the Gini Merchant API, you will have to perform the following easy steps:

1. register your application
2. obtain an access token

For general information about the Gini Merchant API, see overview.

Register Your Application

Before you can use the Gini Merchant API in your application, you need a valid client ID and a client secret. If you don't have the client ID and the client secret already, please contact your sales representative.

Obtain an Access Token

obtain an access token

curl -v -X POST --data-urlencode 'username=random@example.org'
        --data-urlencode 'password=geheim'
        -H 'Content-Type: application/x-www-form-urlencoded'
        -H 'Accept: application/json'
        -u 'client-id:client-secret'
        'https://user.gini.net/oauth/token?grant_type=password'

the JSON response will look similar to

{
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

6c470ffa-abf1-41aa-b866-cd3be0ee84f4 is the access token which can be used for API requests.

All requests to the Gini Merchant API are made on behalf of the user authorized by the access token. For now, let's assume that you've already created an user. If not, for the details on how to do so please read User Center API.

In order to get an access token for the Gini account, run the example command on the right (don't forget to replace random@example.org with your username and geheim with your password as well as client-id with your client ID and client-secret with your client secret).

Overview of the Gini Merchant API

This section provides general information about the Gini Merchant API.

IPv6 Compatibility

IPv6 compatibility example

    $ host merchant-api.gini.net
    merchant-api.gini.net has address 46.245.182.118
    merchant-api.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::6

    $ host user.gini.net
    user.gini.net has address 46.245.182.124
    user.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::2

Gini Merchant API and User Center are accessible from legacy IPv4 and IPv6 networks. The protocol precedence depends on your operating system and configuration if both protocols are enabled.

Media Types

the media types consumed and produced by the Gini Merchant API look like this

    application/vnd.gini.<version>+json

Custom media types are used in the API to let the consumers choose the version of the data format they wish to receive. This is done by adding one or more of the following media types to the Accept header when a request is made. media types are specific to resources, allowing them to change independently and supporting formats that other resources don't.

API Versions

Currently there is one stable version of the Gini Merchant API. Future versions can be requested using a specific Accept header. This is primarily for testing new extractions but may affect other parts of the API as well.

Version 1 (v1)

v1 media type

    Accept: application/vnd.gini.v1+json

Gini Merchant API v1 is stable and will remain backwards compatible. Please contact us via api@gini.net if you have any problems.

Developers are strongly encouraged to explicitly specify the required version of the Gini Merchant API using the HTTP/1.1 Accept header (see the example) because by default the requests are treated as requests to version 1 (v1) of the API.

Authentication

Only authenticated users are allowed to make API requests. The Gini API uses the OAuth 2.0 protocol with bearer tokens for authentication.

In order to use the API in your application, you first have to register your application with Gini. Afterwards your application should request an access token from the Gini Authorization Server and use it to access the Gini Merchant API.

Security

The Gini Merchant API is only accessible over HTTPS. Please make sure that your application validates the relevant X.509 certificates (e.g. common name matches hostname, issuing CA is trusted, etc.).

Client Errors

HTTP response codes

The API uses idiomatic HTTP status codes to indicate if a request was successful or not and whether it should be repeated.

Error Entity

error entity response

{
  "message": "Validation of the request entity failed",
  "requestId": "8896f9dc-260d-4133-9848-c54e5715270f"
}

In case of an error, the Gini Merchant API always returns a JSON object with further information about the occurred error. The JSON object consists of the following properties:

Payment Requests

The Gini Merchant API provides the service of creating and handing over payment requests. A payment request is created by an invoicing party and is resolved by a payment provider or using a QR code. Only the EPC QR code created from a payment request supports currently channel tracking. See pay-api for more information about resolving payment requests.

Getting a list of payment providers

A payment provider is a Gini partner which integrated the GiniPay for Banks SDK into their mobile apps for Android or iOS. The GiniPay for Banks SDK allows to receive and resolve payment requests and integrates with the payment functionality of the banking app. The GiniPay for Banks SDK uses deep links to handle payments.

Payment providers are handled by Merchant API.

get the list

GET /paymentProviders
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+json

yields a list of payment provider objects

[
  {
    "id": "7e72441c-32f8-11eb-b611-c3190574373c",
    "name": "Sparkasse",
    "appSchemeIOS": "ginipay_sparkasse",
    "packageNameAndroid": "de.sparkasse",
    "minAppVersion" : {
      "ios": "4.3.2",
      "android": "3.5.1"
    }
  },
  {
    "id": "9a9b41f2-32f8-11eb-9fb5-e378350b0392",
    "name": "Commerzbank",
    "appSchemeIOS": "ginipay_coba",
    "packageNameAndroid": "com.commerzbank",
    "minAppVersion" : {
      "ios": "7.7.2",
      "android": "6.9.1"
    }
  },
  ...
]

Response

List of payment provider objects:

Getting a Payment Provider

get the payment provider

GET /paymentProviders/7e72441c-32f8-11eb-b611-c3190574373c
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+json

yields the payment provider object

{
  "id": "7e72441c-32f8-11eb-b611-c3190574373c",
  "name": "Sparkasse",
  "appSchemeIOS": "ginipay_sparkasse",
  "packageNameAndroid": "de.sparkasse",
  "minAppVersion" : {
    "ios": "4.3.2",
    "android": "3.5.1"
  }
}

Response

Creating Payment Requests

Payment Requests are handled via Merchant API using header application/vnd.gini.v1+json.

create a payment request

POST /paymentRequests HTTP/1.1
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Content-Type: application/vnd.gini.v1+json

with

{
  "paymentProvider": "9a9b41f2-32f8-11eb-9fb5-e378350b0392",
  "recipient": "Zalando AG",
  "iban": "DE02300209000106531065",
  "bic": "CMCIDEDDXXX",
  "amount": "335.50:EUR",
  "purpose": "ReNr AZ356789Z"
}

response

HTTP/1.1 201 Created
X-Request-Id: 7b5a7f79-ae7c-4040-b6cf-25cde58ad937
Location: https://merchant-api.gini.net/paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000
Content-Type: application/vnd.gini.v1+json

Request

Getting a Payment Request

Payment Requests can be retrieved from Merchant API as json (using application/vnd.gini.v1+json), as Gini QR code (using application/vnd.gini.v1+qr+png) or as EPC QR Code (using application/vnd.gini.v1+epcqr+png).

get a payment request from Merchant API as json

GET /paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+json

response

{
  "createdAt": "2020-12-07T15:50:23",
  "recipient": "Zalando AG",
  "iban": "DE02300209000106531065",
  "requesterUri": "ginipay-example://payment-requester?paymentRequestId=b4bd3e80-7bd1-11e4-95ab-000000000000",
  "bic": "CMCIDEDDXXX",
  "amount": "335.50:EUR",
  "purpose": "ReNr AZ356789Z",
  "status": "paid",
  "trackingHistory": [
    {
      "scannedAt": "2020-12-07T15:55:30",
      "trackingId: "checkout"
    }
  ],
  "_links": {
    "paymentProvider": "https://merchant-api.gini.net/paymentProviders/7e72441c-32f8-11eb-b611-c3190574373c",
     "_self": "https://merchant-api.gini.net/paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000"
  }
}

Response

Alternatively a payment request can be retrieved as a payment QR code using content negotiation.

Generating QR Codes

Payment Requests can be retrieved from Merchant API as QR codes using content negotiation. Currently, Gini QR code (using application/vnd.gini.v1+qr+png for png or application/vnd.gini.v1+qr+pdf for pdf) or EPC QR Code (using application/vnd.gini.v1+epcqr+png) are supported. Channel tracking is currently only supported for EPC QR codes.

Generate a Gini QR code PNG file

The following example generates a Gini QR code PNG file for the given payment request.

GET /paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+qr+png

response

The QR code encoded as `image/png`.

Generate a Gini QR code PDF file

The following example generates a Gini QR code PDF file for the given payment request.

GET /paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+qr+pdf

response

response is a byte array which can be read as a PDF file.

Generate an EPC QR code with tracking

The EPC QR Code can be retrieved with an embedded tracking id. The tracking id is used to create the tracking history of the payment request if the QR code is scanned. The payment request is not changed if a QR code is created.

GET /paymentRequests/b4bd3e80-7bd1-11e4-95ab-000000000000?trackingId=checkout
Host: merchant-api.gini.net
Authorization: BEARER c796535e-32e4-11eb-b966-e30e07dee3dc
Accept: application/vnd.gini.v1+epcqr+png

response

The QR code encoded as `image/png`.

Managing Anonymous Gini Accounts

In order to achieve best results, the Gini Merchant API must be able to track the requests down to individual users.

Gini offers various ways to perform requests on behalf of the individual users without requiring physical interaction. Depending on your use case and your product's architecture, the following API authentication methods are available:

• trusted

  Your application communicates with the Gini Merchant API via a common backend that runs on a trusted device. Each request states which user the request is made for via the application's user identifier. No account management is required.

• untrusted

  On the first API usage, your application creates an anonymous Gini user in the background and uses those account credentials for subsequent requests. This works best for (mobile) applications where the app communicates directly with the Gini Merchant API on an untrusted device.

Communicating with the Gini Merchant API via Backend / Gateway

request the list of user1's documents

curl -v -H 'Accept: application/vnd.gini.v1+json'
    -u 'client-id:client-secret'
    -H 'X-User-Identifier: user1'
    https://merchant-api.gini.net/documents

This authentication scheme is based on HTTP Basic Authentication. Your application needs to use HTTP Basic Authentication to authenticate itself with the Gini Merchant API. Additionally, another header called X-User-Identifier is sent together with the Authorization header in one request. This header is used by the API to identify individual users. Your application is free to choose whatever value it wants for the header, as long as the following constraints are met:

• Each user's identifier must be unique.
• Once set for a user, the identifier must remain the same.

authenticating on behalf of a derived user

The access token is only needed if it is created by a trusted system (eg. backend or gateway) and used by an untrusted device (eg. smartphone).

curl -v -X POST -H 'X-User-Identifier: user1'
    -H 'Accept: application/vnd.gini.v1+json'
    -u 'client-id:secret' 'https://merchant-api.gini.net/login'

POST https://merchant-api.gini.net/login
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: merchant-api.gini.net
accept: application/vnd.gini.v1+json

example response

{
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

The returned access token can now be used to make requests to the Gini Pay API on behalf of the user. To do so, send the access token as a bearer token in the Authorization request header:

GET /documents HTTP/1.1
Host: merchant-api.gini.net
Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4
Accept: application/vnd.gini.v1+json
Connection: close

Direct Communication between Client Devices and the Gini Merchant API

Gini offers the User Center API (UC API) to work with the Gini users. Here is a quick step-by-step guide that outlines how to create and use a new anonymous Gini account. Each step links to the corresponding section in the UC API where you can read more details about it.

1. obtain the client token
2. create a new user
3. log in as a new user
4. make API requests with the access token

Authenticate the Client

obtain the client token

curl -v -H 'Accept: application/json'
    -u 'client-id:client-secret'
    'https://user.gini.net/oauth/token?grant_type=client_credentials'

the successful response will have HTTP status 200 and the client access token 1eb7ca49-d99f-40cb-b86d-8dd689ca2345 will be returned

{
  "access_token":"1eb7ca49-d99f-40cb-b86d-8dd689ca2345",
  "token_type":"bearer","expires_in":43199,"scope":"read"
}

Before you are able to use the UC API, you need to obtain a client access token. The client access token authorizes your client (i.e. your application) against the UC API and allows you to create a new user.

At this point it is assumed that you already have the client ID client-id and the client secret client-secret. These will authorize your client (with HTTP Basic Authentication) to obtain the client access token, see the example on the right.

For more details see the corresponding UC API section.

Create a New User

create a new user

curl -v -X POST --data '{"email":"random@example.org", "password":"geheim"}'
    -H 'Content-Type: application/json'
    -H 'Accept: application/json'
    -H 'Authorization: BEARER 1eb7ca49-d99f-40cb-b86d-8dd689ca2345'
    'https://user.gini.net/api/users'

the above command creates a new user random@example.org with password geheim. If the creation was successful, the HTTP response has status 201 and contains the Location header pointing to the new user. Your client is now allowed to create a new user authorized by the client access token.

Once the client access token is successfully obtained, it's time to create a new user. To do so we require two more values: a username and a password. The username must be represented by a correct email address whose domain part is easily linkable to your application. For example, if your company is called Example Inc. then app.example.org would be a good domain name to use for your application's user accounts.

For more details see the corresponding UC API section.

Authenticate on behalf of a New User

login as a new user

curl -v -X POST --data-urlencode 'username=random@example.org'
    --data-urlencode 'password=geheim'
    -H 'Content-Type: application/x-www-form-urlencoded'
    -H 'Accept: application/json' -u 'client-id:client-secret'
    'https://user.gini.net/oauth/token?grant_type=password'

After the new user is created, you can log in. Note that log in request uses HTTP Basic Authentication with the client ID as a username and with the client secret as a password. It does not require a client access token. The request response will contain an access token that can be used to make API requests on behalf of the new user.

For more details see the corresponding UC API section.

Make API Requests with the Access Token

use the access token you obtained to make API requests

GET /documents HTTP/1.1
Host: merchant-api.gini.net
Authorization: BEARER 760822cb-2dec-4275-8da8-fa8f5680e8d4
Accept: application/vnd.gini.v1+json
Connection: close

In order to make API requests, send the access token as a bearer token in the Authorization request header.

User Center API

Gini's User Center offers an API to programmatically create new Gini accounts and to make API requests on behalf of the created user.

Client Authentication

All access to the User Center API requires client authentication. A client can authenticate itself with the Client Credentials Grant described in RFC 6749. In short, the client exchanges its client ID and client secret for an access token.

Request

get a client access token

curl -v -H 'Accept: application/json'
    -u 'client-id:secret'
    'https://user.gini.net/oauth/token?grant_type=client_credentials'

GET /oauth/token?grant_type=client_credentials HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json

example response

{
  "access_token":"74c1e7fe-e464-451f-a6eb-8f0998c46ff6","token_type":"bearer","expires_in":3599
}

In order to get a client access token, send a GET request to /oauth/token?grant_type=client_credentials. The request must contain a basic HTTP access authorization header with the client ID as a username and the client secret as a password.

The client can now use the returned access token to make requests to the User Center API by sending the token as a bearer token in the Authorization request header:

GET /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Authenticating on behalf of a User

authenticating on behalf of a user

curl -v -X POST --data-urlencode
    'username=some_user@example.com'
    --data-urlencode 'password=supersecret'
    -H 'Content-Type: application/x-www-form-urlencoded'
    -H 'Accept: application/json'
    -u 'client-id:secret' 'https://user.gini.net/oauth/token?grant_type=password'

POST /oauth/token?grant_type=password HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json
Content-Type: application/x-www-form-urlencoded

username=some_user@example.com&password=supersecret

example response

{
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

The returned access token can now be used to make requests to the Gini Merchant API on behalf of the user. To do so, send the access token as a bearer token in the Authorization request header:

GET /documents HTTP/1.1
Host: merchant-api.gini.net
Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4
Accept: application/vnd.gini.v1+json
Connection: close

The Resource Owner Password Credentials Grant can be used to exchange a user's email address and a password with an access token. The access token can then be used to make requests to the Gini API on behalf of the user.

Request

Note that the client must authenticate itself using basic HTTP access authentication with its ID as a username and its secret as a password.

Creating a New User

creating a new user

curl -v -X POST --data '{"email":"some_user@example.com", "password":"supersecret"}'
    -H 'Content-Type: application/json'
    -H 'Accept: application/json'
    -H 'Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6'
    'https://user.gini.net/api/users'

POST /api/users HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

{"email":"some_user@example.com","password:"supersecret"}

example response

HTTP/1.1 201 Created
Location: https://user.gini.net/api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e
Content-Length: 0

In order to create a new user, submit a POST request to /api/users.

Request

If the request entity was invalid (missing field(s), password < 6 characters etc.) or a user with that email address already exists, the API will respond with 400 Bad Request.

Retrieving User Information

retrieving user information

GET /api/users/88a28076-18e8-4275-b39c-eaacc240d406 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Response

{
  "id":"88a28076-18e8-4275-b39c-eaacc240d406",
  "email":"some_user@example.com"
}

Information about a user can be retrieved with a GET request to /api/users/{userId}

Response

Changing a User's Password and/or Email

change a user's password and/or email

PUT /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

with

{"oldPassword":"supersecret","password:"anothersecret"}

or

{"oldEmail":"old@email.com","email:"my.new@email.com"}

or

{
 "oldPassword":"supersecret",
 "password":"anothersecret",
 "oldEmail":"old@email.com",
 "email":"my.new@email.com"}

A user's password and/or email can be changed with a PUT request to /api/users/{userId}. In order to update a user's password and/or email, the current password/email must be provided.

Request

oldPassword The user's current password. password | The password to which the user's password should be changed to. oldEmail | The user's current email. email | The email to which the user's email should be changed to.

Deleting a User

delete a user

DELETE /api/users/16aecc72-8032-4df6-9686-eaf4ec9532b8 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

An existing user can be deleted with a DELETE request to /api/users/{userId}. This also deletes all data associated with that user (e.g. access tokens, documents and extractions).

Troubleshooting

If you have trouble using the Gini Merchant API and you need to contact the support, there is some information you should always provide in order for us to help you quickly and efficiently.

X-Request-Id

The request id is generated for every request against the Gini Merchant API and tracked through the whole system. It is included in every response you receive from the Gini Merchant API as the HTTP header X-Request-Id. Please refer to it when you contact our support.