Page Comparison

...

Submit documents by sending a POST request to the /documents resource path. After successful submission, the location of the new document is returned in the Location header.

The Gini Pay API currently supports two different variants of uploads, one optimized for web applications running in a web browser and the other for all other types of clients. The first variant optimized for web applications expects the documents to be uploaded using a multipart/form-data encoding method. The second variant for all other clients simply uses the request body (independent of the request Content-Type) as the document.

...

...

Pages that are part of the document are referred to as partial documents. If you want to upload a page (or a page picture) that belongs to the document, your request header should additionally include Content-Type field with application/vnd.gini.v1.partial+png value or application/vnd.gini.v1.partial+pdf in case of PDF page. See the examples below.

In case you want to submit a parsed QR code, please use application/vnd.gini.v1.partial+qr+json. The parsing of the QR field fields is optional. The paymentdata needs to contain at least the iban and the paymentRecipient keys. Hence, but the values can be emptythe minimal valid QR code body could be the following:

{
  "qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65&currency=EUR",
  "paymentdata": {
    "iban": "DE01234567898765432101",
    "paymentRecipient": "Telekom GmbH"
  }
}

Mandatory QR fields

Optional QR fields

See the complete QR request example below.

Request

In order to upload a page picture or a partial document, specify a different content type:

Headers

...

• branchid is used to group uploads from a specific client (eg (e.g. branches for banks)

• deviceclass specifies from which kind of device the upload comes from. E. Egg. if it was uploaded from a desktop computer or a smartphone.

...

Errors

//upload a partial document

//variant for web applications running in a web browser with access token:

curl -H 'Authorization: BEARER <token>'
    --form 'file=@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents
    
//variant for other types of applications with access token:

curl -H 'Authorization: BEARER <token>'
    --data-binary '@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents?filename=file.JPEG

//or with X-User-identifier (see how to setup X-User-identifier):

curl -H 'X-User-Identifier: user1'
    --form 'file=@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -u 'client-id:client-secret'
    -i https://pay-api.gini.net/documents
    
// variant for QR code 
curl -H 'Authorization: BEARER <token>'
    --form 'data.json={
        "qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65&currency=EUR",
          "paymentdata": {
            "amountToPay": "25.79:EUR",
            "paymentRecipient": "Telekom GmbH",
            "iban": "<IBAN>DE01234567898765432101",
            "bic": "<BIC>SPESDE3EXXX",
            "paymentReference": "<REFERENCE>Nr.12345"
          }
      }'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents

...

After successfully uploading all pages as partial documents, announce their locations to the extraction system by uploading a composite document, which is a simple JSON file with corresponding locations of partial documents.

...

...