Documentation Powered by ReDoc

Payment-method API (0.2.0)

Download OpenAPI specification:Download

API for an external payment method that is called by the enfore platform

Status

Get the status of the external payment method for a specific context

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
service_location_id
required
string [ 1 .. 256 ] characters

The ID of the service location the payment method will/may be used at.

cash_register_id
required
string [ 1 .. 256 ] characters

The ID of the cash register the payment method will/may be used on.

client_language
required
string

The language that the client UI uses. This can be used by the EPM implementation to provide localized texts for the availability info.

The parameter is a "language tag" (see https://www.w3.org/TR/ltli/#dfn-language-tag).

customer
any (ContactInformation)

Information about a contact.

Depending on the type of contact (private person, organization, organization with representative) and whether the entities are modeled as contacts via the contacts API, different structures are used.

Note that this structure is used to reference plain contacts as well as contacts with a specific role such as customer or suppliers. Depending on the usage context, not all types of contact informations may be usable.

customer_identifiers
Array of any (CustomerIdentifier)

Identifiers available for identification of the customer that will/may use the external payment method.

Responses

200

Status information for the external payment method

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/status/
/org/{org-id}/status/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "service_location_id": "string",
  • "cash_register_id": "string",
  • "client_language": "string",
  • "customer":
    {
    },
  • "customer_identifiers":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "AVAILABLE",
  • "additional_information":
    [
    ]
}

Customers

Determine whether a customer identifier is valid

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
identifier_code
required
string [ 1 .. 256 ] characters

The identifier code to validate.

Usually scanned from a barcode or QR code or entered manually by the merchant/user.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/customers/verify
/org/{org-id}/external-payments/customers/verify

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "identifier_code": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
VerifyCustomerSuccess
Copy
 Expand all Collapse all
{
  • "@type": "VerifyCustomerSuccess",
  • "status": "UNKNOWN_IDENTIFIER",
  • "customer":
    {
    },
  • "payment_vouchers":
    [
    ]
}

Vouchers

Determine whether a voucher is valid

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
identifier_code
required
string [ 1 .. 256 ] characters

The identifier code to validate.

Usually scanned from a barcode or QR code or entered manually by the merchant/user.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/vouchers/validate
/org/{org-id}/external-payments/vouchers/validate

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "identifier_code": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
ValidatePaymentVoucherSuccess
Copy
 Expand all Collapse all
{
  • "@type": "ValidatePaymentVoucherSuccess",
  • "status": "UNKNOWN_IDENTIFIER",
  • "voucher_description": "string",
  • "identifier": "string",
  • "external_data": "string"
}

Payment Computation

Compute possible payments based on basket, customer and vouchers.

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
basket
required
object (SalesBasket)
selected_payment_vouchers
Array of objects (SelectedPaymentVoucher)

The payment vouchers that were both found to be valid and have been selected by the user.

Note that this list may be null/empty!

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/compute-possible-payments
/org/{org-id}/external-payments/compute-possible-payments

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "basket":
    {
    },
  • "selected_payment_vouchers":
    [
    ],
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
ComputePossiblePaymentsSuccess
Copy
 Expand all Collapse all
{
  • "@type": "ComputePossiblePaymentsSuccess",
  • "possible_payments":
    [
    ],
  • "declined_vouchers":
    [
    ]
}

Compute necessary offset payouts for a void based on the void basket and original invoice and payments.

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
void_basket
required
object (VoidBasket)
original_sales_basket
object (OriginalSalesBasketForVoid)
original_epm_payments
required
Array of objects (OriginalPayment)
context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/compute-necessary-offset-payouts-for-void
/org/{org-id}/external-payments/compute-necessary-offset-payouts-for-void

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "void_basket":
    {
    },
  • "original_sales_basket":
    {
    },
  • "original_epm_payments":
    [
    ],
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
ComputeNecessaryOffsetPayoutsForVoidSuccess
Copy
 Expand all Collapse all
{
  • "@type": "ComputeNecessaryOffsetPayoutsForVoidSuccess",
  • "necessary_offset_payouts":
    [
    ]
}

Payment Processing

Authorize or capture a payment

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payment_request_id
required
string

The ID of the payment request for which the payment is to be authorized/captured.

requested_amount
required
object (Money)

A Money represents a monetary value (i.e., a currency and an amount), for example "120 EUR" or "2,500.75 USD".

included_tip_amount
required
object (Money)

A Money represents a monetary value (i.e., a currency and an amount), for example "120 EUR" or "2,500.75 USD".

invoice_or_credit_memo_information
required
Array of objects (InvoiceOrCreditMemoInformation)

Information about the invoices/credit memos that the payment is to be made for.

Note that the enfore platform currently only supports payments for single invoices/ credit memos. The list is used as that functionality is planned to be extended in the future.

payment_method_configuration
required
object (PaymentMethodConfiguration)

Information about the configuration for an external payment method that is passed into the payment/payout calls.

external_data
string

The external data that was provided by the "compute payments" endpoint for the "possible payment" that this payment is derived from.

Only present when the payment is derived from a "possible payment" and when that "possible payment" did contain external data.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/authorize-or-capture-payment
/org/{org-id}/external-payments/payment-processing/authorize-or-capture-payment

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payment_request_id": "string",
  • "requested_amount":
    {
    },
  • "included_tip_amount":
    {
    },
  • "invoice_or_credit_memo_information":
    [
    ],
  • "payment_method_configuration":
    {
    },
  • "external_data": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
AuthorizeOrCapturePaymentSuccess
Copy
 Expand all Collapse all
{
  • "@type": "AuthorizeOrCapturePaymentSuccess",
  • "status": "AUTHORIZED",
  • "processed_amount":
    {
    },
  • "payment_reference": "string",
  • "payment_processing_data": "string",
  • "custom_receipt_document_information":
    [
    ]
}

Capture a payment

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payment_request_id
required
string

The ID of the payment request whose payment is to be captured.

payment_reference
required
string

The payment reference of the payment to capture as provided by the AuthorizeOrCapturePayment call.

payment_processing_data
string

The payment processing data of the payment to capture as provided by the AuthorizeOrCapturePayment call.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/capture-payment
/org/{org-id}/external-payments/payment-processing/capture-payment

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payment_request_id": "string",
  • "payment_reference": "string",
  • "payment_processing_data": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
CapturePaymentSuccess
Copy
 Expand all Collapse all
{
  • "@type": "CapturePaymentSuccess",
  • "payment_processing_data": "string",
  • "custom_receipt_document_information":
    [
    ]
}

Cancel a payment

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payment_request_id
required
string

The ID of the payment request whose payment is to be canceled.

payment_reference
required
string

The payment reference of the payment to cancel as provided by the AuthorizeOrCapturePayment call.

payment_processing_data
string

The payment processing data of the payment to cancel as provided by the AuthorizeOrCapturePayment call.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/cancel-payment
/org/{org-id}/external-payments/payment-processing/cancel-payment

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payment_request_id": "string",
  • "payment_reference": "string",
  • "payment_processing_data": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
CancelPaymentSuccess
Copy
 Expand all Collapse all
{
  • "@type": "CancelPaymentSuccess",
  • "payment_processing_data": "string"
}

Revert a payment

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payout_request_id
required
string

The ID of the payout request for which the payment is to be reverted.

payment_request_id
required
string

The ID of the payment request whose payment is to be reverted.

payment_reference
required
string

The payment reference of the payment to revert as provided by the AuthorizeOrCapturePayment call.

payment_processing_data
string

The payment processing data of the payment to revert as provided by the AuthorizeOrCapturePayment call.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/revert-payment
/org/{org-id}/external-payments/payment-processing/revert-payment

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payout_request_id": "string",
  • "payment_request_id": "string",
  • "payment_reference": "string",
  • "payment_processing_data": "string",
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
RevertPaymentSuccess
Copy
 Expand all Collapse all
{
  • "@type": "RevertPaymentSuccess",
  • "payout_reference": "string",
  • "payout_processing_data": "string",
  • "payment_processing_data": "string",
  • "custom_receipt_document_information":
    [
    ]
}

Grant a payout

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payout_request_id
required
string

The ID of the payout request for which the payout is to be granted.

requested_amount
required
object (Money)

A Money represents a monetary value (i.e., a currency and an amount), for example "120 EUR" or "2,500.75 USD".

invoice_or_credit_memo_information
required
Array of objects (InvoiceOrCreditMemoInformation)

Information about the invoices/credit memos that the payout is to be made for.

Note that the enfore platform currently only supports payouts for single invoices/ credit memos. The list is used as that functionality is planned to be extended in the future.

offset_for_payment_request_id
string

The ID of the payment request which the payout shall offset.

offset_for_payment_reference
string

The payment reference of the payment which the payout shall offset.

offset_for_payment_processing_data
string

The payment processing data of the payment which the payout shall offset

external_data
string

External data that was previously provided for the payout.

For now, this is only possible for "offset payouts" computed via the "compute necessary offset payouts for void" endpoint.

payment_method_configuration
required
object (PaymentMethodConfiguration)

Information about the configuration for an external payment method that is passed into the payment/payout calls.

context
required
object (PaymentContext)

Context information about the payment that the external payment method is going to be used for.

Contains information about the customer, scanned identifiers, service location etc. to allow the external service to a) decide on availability and b) provide additional information to display in the UI.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/grant-payout
/org/{org-id}/external-payments/payment-processing/grant-payout

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payout_request_id": "string",
  • "requested_amount":
    {
    },
  • "invoice_or_credit_memo_information":
    [
    ],
  • "offset_for_payment_request_id": "string",
  • "offset_for_payment_reference": "string",
  • "offset_for_payment_processing_data": "string",
  • "external_data": "string",
  • "payment_method_configuration":
    {
    },
  • "context":
    {
    }
}

Response samples

Content type
application/json
Example
GrantPayoutSuccess
Copy
 Expand all Collapse all
{
  • "@type": "GrantPayoutSuccess",
  • "processed_amount":
    {
    },
  • "payout_reference": "string",
  • "payout_processing_data": "string",
  • "custom_receipt_document_information":
    [
    ]
}

Cancel a payout

path Parameters
org-id
required
string

ID of the organization whose data is being accessed.

Request Body schema: application/json
payout_request_id
required
string

The ID of the payout request whose payout is to be canceled.

payout_reference
required
string

The payout reference of the payout to cancel as provided by the GrantPayout/RevertPayment call.

payout_processing_data
string

The payout processing data of the payout to cancel as provided by the GrantPayout/RevertPayment call.

Responses

200

The result of the request.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

post /org/{org-id}/external-payments/payment-processing/cancel-payout
/org/{org-id}/external-payments/payment-processing/cancel-payout

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "payout_request_id": "string",
  • "payout_reference": "string",
  • "payout_processing_data": "string"
}

Response samples

Content type
application/json
Example
CancelPayoutSuccess
Copy
 Expand all Collapse all
{
  • "@type": "CancelPayoutSuccess",
  • "payout_processing_data": "string"
}