Skip to main content

Payment

Introduction

The Connector Application for "Electronic Payment" allows external payment gateways to interact with the SOClass-based Customs system to exchange information on electronic invoicing and electronic payments.

In the following, we will refer to the external system that provides features of electronic invoicing and payment as Payment Gateway.

The Connector Payment Module allows the Payment Gateway to receive information on invoices or payment orders from the SOClass based Customs system as well as to send information of payments being processed to the SOClass based Customs system.

img

Section Sending Invoices Information contains details on the web services that the Payment Gateway should support and that will be consumed by the Connector application to update payment order information.

The next section, Receive Payment Notification, describes the web service published by Connector application that is consumed by the Payment Gateway to send details about an executed payment.

Receive Payment Notification

This endpoint allows the external Payment Gateway to send the information of a payment for a particular invoice.

ParameterDescription
HTTP REQUESThttps://CONNECTOR-URL/api/v1/payment/notification
VERBPOST
HEADER
 		Header: Authorization: Bearer <TOKEN>
Format: [JSON]

INPUT Fields

FieldTypeDescription
idIntegerUnique identifier of this notification.
typeString (255 chars)Notification type, e.g. invoice.paid, invoice.view, etc.
createdAtString (Datetime ISO 8601 format)Datetime of creation of this notification.
pendingWebhooksIntegerA number indicating pending webhooks that sill needs to be notified, normally 0.
dataObjectJSON Object containing details of the invoice.
data.idString (255 chars)Unique identifier of the invoice.
data.statusString (255 chars)Invoice status (either PAID, UNPAID, PENDING, VOID).
data.totalAmountDecimal numberInvoice total amount.
data.documentNoString (255 chars)Unique identifier of the document the invoice refers to.
data.paymentNoString (255 chars)Payment reference (the unique identifier of this payment).
data.paymentDateString (Datetime ISO 8601 format)Datetime of the payment execution.
data.paymentModeString (255 chars)String indicating the mode of payment (either CASH, DIRECT_PAYMENT, etc.)
data.collectorString (255 chars)String indicating the bank or payment operator that executed or collected the payment.
data.bankCodeString (255 chars)String indicating the bank or payment operator that executed or collected the payment.
data.additionalFieldsObject (array of <code,value> pairs)An object containing an array of <code,value> pairs that brings additional information of the invoice. These are passed during invoice creation.

EXAMPLE OF REQUESTS

Request

curl https://CONNECTOR-URL/api/v1/payment/notification  \
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu' \
-X POST \
-d '{
  "id": 4214,
  "type": "invoice.paid",
  "data": {
    "id": "MAN2020-b7598",
    "status": "PAID",
    "totalAmount": 50000,
    "documentNo": "CUO11-574-2020|TEST_PAY|4",
    "paymentNo": "gup1dc4",
    "paymentDate": "2020-06-05T08:03:05.551832",
    "paymentMode": "CARDS",
    "collector": "BGUBA1",
    "bankCode": "BGUBA1",
    "additionalFieldDtos": [
      {
        "code": "USN",
        "value": "USN-2000024"
      },
      {
        "code": "INVOICE_ID",
        "value": "4"
      },
      {
        "code": "BOL_REFERENCE",
        "value": "TEST_PAY"
      },
      {
        "code": "CUSTOMS_OFFICE",
        "value": "CUO11"
      }
    ]
  },
  "createdAt": "2020-06-05T08:03:35.404869",
  "pendingWebhooks": 0
}'

Response HTTP/1.1 200 OK

{   
  "id": 4214,
  "type": "invoice.paid",
  "receivedAt": "2020-06-05T11:03:35.404869",
}

Sending Invoices Information

The external Payment Gateway receives information about the invoices, or payment requests, that will need to be paid. This information includes the amount to be paid, list of invoice lines as well as other details that can be used by the external Payment Gateway to properly display payment information to the end-user.

img

Create Invoice

This method is used by the Connector Application for "Electronic Payment" to send information of new invoices to be created to the Payment Gateway.

ParameterDescription
HTTP REQUESThttps://external-system/invoices
VERBPOST
HEADER
 		Header: Authorization: Bearer <TOKEN>
Accepted Format: [JSON]

ARGUMENTS

Refer to the Invoice object, which is the input payload used in this web service.

RESPONSE ATTRIBUTES

ParameterTypeMandatoryDescription
invoiceNumberStringmandatoryID of the created invoice
statusStringmandatoryStatus of the invoice
invoiceURLStringmandatoryURL to the invoice

EXAMPLE OF REQUESTS

Request

curl https://external-system/invoices \ 
-X POST \ 
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu' \
-d ' {
    "type": "SAD",
    "expirationDate": "2019-02-10T12:15:47",
    "date": "2005-02-10T12:15:47",
    "amount": "45.00",
    "currency": "USD",
    "discount": "10.00",
    "totalAmount": "35.00",
    "customerCode": "BTLCI01",
    "representativeCode": "8978",
    "receiptNumber": "ABCD1234",
    "merchantReference": "CAAB1-L-123",
    "merchantReferenceURL": "http://issuer-url/declaration/CAAB1-L-123",
    "userReference": "BOLLORE01235",
    "items": [
        {
            "name": "DD",
            "amount": "20.00",
            "beneficiaryCode": "21"
        },
        {
            "name": "RST",
            "amount": "25.00",
            "beneficiaryCode": "22"
        }
    ],
    "invoiceBeneficiaries": [
        {
            "beneficiaryCode": "21",
            "amount": "20.00"
        },
        {
            "beneficiaryCode": "22",
            "amount": "25.00"
        }
    ],
    "additionalFields": [
        {
            "code": "customsDeclarationType",
            "value": "IM"
        },
        {
            "code": "customsOffice",
            "value": "CAAB1"
        },
        {
            "code": "customsRegime",
            "value": "42"
        },
        {
            "code": "customsRegistrationNum",
            "value": "12746"
        },
        {
            "code": "customsRegistrationDate",
            "value": "2018-01-01Z"
        },
        {
            "code": "customsAssessmentNum",
            "value": "123"
        },
        {
            "code": "customsAssessmentSerial",
            "value": "L"
        },
        {
            "code": "customsAssessmentDate",
            "value": "2018-01-01"
        },
        {
            "code": "customsDeclarantCode",
            "value": "8978"
        },
        {
            "code": "customsDeclarantName",
            "value": "Declarant XYZ"
        },
        {
            "code": "customsDeclarantAddress",
            "value": "3, Park Lane, City, State"
        },        {
            "code": "documentNo",
            "value": "TST1201901260"
        },
        {
            "code": "documentDate",
            "value": "2018-01-01Z"
        },        {
            "code": "documentReference",
            "value": "LIC201900001430"
        }
    ]
}
'

Response HTTP/1.1 200 OK

{
    "invoiceNumber": "SAD2019-186a0",
    "status": "UNPAID",
    "invoiceUrl": ""
}

Void Invoice

This endpoint allows the Connector Application for "Electronic Payment" to send the external Payment Gateway a request to void (or cancel) an existing invoice.

ParameterDescription
HTTP REQUESThttps://external-system/invoices/:invoiceNumber/void
VERBPATCH
HEADER
 		Header: Authorization: Bearer <TOKEN>
Format: [JSON]

EXAMPLE OF REQUESTS

Request

curl https://external-system/invoices/SAD2019-186a0/void \ 
-X PATCH \ 
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu'

Response HTTP/1.1 200 OK

{
    "type": "SAD",
    "expirationDate": "2019-02-10T12:15:47",
    "date": "2019-02-10T12:15:47",
    "amount": 45,
    "invoiceNumber": "SAD2019-0",
    "status": "VOID",
    "tax": 0,
    "fee": 0,
    "currency": "USD",
    "discount": 10,
    "totalAmount": 35,
    "customerCode": "BTLCI01",
    "representativeCode": "8978",
    "merchantReference": "CAAB1-L-123",
    "merchantReferenceURL": "http://issuer-url/declaration/CAAB1-L-123",
    "userReference": "BOLLORE01235",
    "merchant": {
        "code": "01",
        "name": "Merchant Name",
        "address": "12, Sunrise Ave."
    },
    "items": [
        {
            "name": "DD",
            "amount": 20,
            "beneficiaryCode": "21"
        },
        {
            "name": "RST",
            "amount": 25,
            "beneficiaryCode": "22"
        }
    ],
    "additionalFields": [
        {
            "code": "customsDeclarationType",
            "value": "IM"
        },
        {
            "code": "customsOffice",
            "value": "CAAB1"
        },
        {
            "code": "customsRegime",
            "value": "42"
        },
        {
            "code": "customsRegistrationNum",
            "value": "12746"
        },
        {
            "code": "customsRegistrationDate",
            "value": "2018-01-01Z"
        },
        {
            "code": "customsAssessmentNum",
            "value": "123"
        },
        {
            "code": "customsAssessmentSerial",
            "value": "L"
        },
        {
            "code": "customsAssessmentDate",
            "value": "2018-01-01"
        },
        {
            "code": "customsDeclarantCode",
            "value": "8978"
        },
        {
            "code": "customsDeclarantName",
            "value": "Declarant XYZ"
        },
        {
            "code": "customsDeclarantAddress",
            "value": "3, Park Lane, City, State"
        },
        {
            "code": "documentNo",
            "value": "TST1201901260"
        },
        {
            "code": "documentDate",
            "value": "2018-01-01Z"
        },
        {
            "code": "documentReference",
            "value": "LIC201900001430"
        }
    ],
    "invoiceBeneficiaries": [
        {
            "amount": 20,
            "beneficiaryCode": "21",
            "beneficiaryName": "ORGANISATION A"
        },
        {
            "amount": 25,
            "beneficiaryCode": "22",
            "beneficiaryName": "ORGANISATION B"
        }
    ]
}

Pay Invoice

This endpoint allows the Connector Application for "Electronic Payment" to send the external Payment Gateway a request to mark an existing invoice as paid within the Customs system.

ParameterDescription
HTTP REQUESThttps://external-system/invoices/:invoiceNumber/pay
VERBPATCH
HEADER
 		Header: Authorization: Bearer <TOKEN>
Format: [JSON]

EXAMPLE OF REQUESTS

Request

curl https://external-system/invoices/SAD2019-186a0/pay \ 
-X PATCH \ 
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu'

Response HTTP/1.1 200 OK

{
    "type": "SAD",
    "expirationDate": "2019-02-10T12:15:47",
    "date": "2019-02-10T12:15:47",
    "amount": 45,
    "invoiceNumber": "SAD2019-0",
    "status": "PAID",
    "tax": 0,
    "fee": 0,
    "currency": "USD",
    "discount": 10,
    "totalAmount": 35,
    "customerCode": "BTLCI01",
    "representativeCode": "8978",
    "merchantReference": "CAAB1-L-123",
    "merchantReferenceURL": "http://issuer-url/declaration/CAAB1-L-123",
    "userReference": "BOLLORE01235",
    "merchant": {
        "code": "01",
        "name": "Merchant Name",
        "address": "12, Sunrise Ave."
    },
    "items": [
        {
            "name": "DD",
            "amount": 20,
            "beneficiaryCode": "21"
        },
        {
            "name": "RST",
            "amount": 25,
            "beneficiaryCode": "22"
        }
    ],
    "additionalFields": [
        {
            "code": "customsDeclarationType",
            "value": "IM"
        },
        {
            "code": "customsOffice",
            "value": "CAAB1"
        },
        {
            "code": "customsRegime",
            "value": "42"
        },
        {
            "code": "customsRegistrationNum",
            "value": "12746"
        },
        {
            "code": "customsRegistrationDate",
            "value": "2018-01-01Z"
        },
        {
            "code": "customsAssessmentNum",
            "value": "123"
        },
        {
            "code": "customsAssessmentSerial",
            "value": "L"
        },
        {
            "code": "customsAssessmentDate",
            "value": "2018-01-01"
        },
        {
            "code": "customsDeclarantCode",
            "value": "8978"
        },
        {
            "code": "customsDeclarantName",
            "value": "Declarant XYZ"
        },
        {
            "code": "customsDeclarantAddress",
            "value": "3, Park Lane, City, State"
        },
        {
            "code": "documentNo",
            "value": "TST1201901260"
        },
        {
            "code": "documentDate",
            "value": "2018-01-01Z"
        },
        {
            "code": "documentReference",
            "value": "LIC201900001430"
        }
    ],
    "invoiceBeneficiaries": [
        {
            "amount": 20,
            "beneficiaryCode": "21",
            "beneficiaryName": "ORGANISATION A"
        },
        {
            "amount": 25,
            "beneficiaryCode": "22",
            "beneficiaryName": "ORGANISATION B"
        }
    ]
}