Please make sure you read the Conventions before continuing with this guide.

Prerequisites

You will need an X-API-KEY and a Basic Access Authentication token generated from your username and password.

Verify the transaction can be paid

You will need to use the following "undocumented" GET endpoint.

https://api.betterez.com/payments/referenced-payments/{transactionId}/{referenceNumber}/status

transactionId: The 24 alphanumeric Id for the transaction they payment is intended to be applied to. referenceNumber: This is a ramdon generated key that identifies the payment in the transaction.

The referenceNumber is generated when the transaction is "completed" and "paid" with a referenced payment in any channel on the Betterez system. This information is usually provided to the end user so they can complete the payment in an authorized payment provider, in this case is probably your system.

Calling this endpoint will return an object with the following structure.

{
  "status": {
    "type": "string",
    "description": "The referenced payment status: success, error, pending, review",
    "enum": ["error", "pending", "success", "review"]
  },
  "result": {
    "type": "object",
    "description": "The referenced payment processing result, if the status is other than pending."
  }
}

If the status is pending you can proceed to complete the payment.

Getting the transaction information

You can get details on the transaction using the endpoint.

https://api.betterez.com/operations/transactions/{transactionId}

Completing the payment

You can accept payment on your system for the total transaction amount, once you completed the processing on your end and are hapy that the payment was completed succesfully you need to notify Betterez so the payment is reflected and tha transaction completed.

You will need to make a PUT request to the following endpoint with the payload described below, the following properties are required: ["provider", "type", "result", "createdAt", "custom", "displayName", "status", "amount", "referenceNumber"]

https://api.betterez.com/operations/transactions/{transactionId}/payments

{
  "provider": {
    "type": "string",
    "description": "The payment method provider name",
  },
  "type": {
    "type": "string",
    "description": "The payment method name"
  },
  "result": {
    "$ref": "PaymentResultFreeForm",
    "description": "The processing result for this payment (this comes from the payment processor used in your system)"
  },
  "createdAt": {
    "$ref": "BzDate",
    "description": "The payment created date"
  },
  "custom": {
    "type": "boolean",
    "description": "Indicates if a custom payment method was used for the payment"
  },
  "displayName": {
    "type": "string",
    "description": "Payment method display name"
  },
  "status": {
    "type": "string",
    "description": "Payment status: 'success' or 'error'",
    "enum": ["success", "error"]
  },
  "amount": {
    "type": "number",
    "format": "float",
    "description": "Payment formatted total amount"
  },
  "referenceNumber": {
    "type": "string",
    "description": "Payment external reference number"
  },
  "authCode": {
    "type": "string",
    "description": "Authorization code for the payment"
  }
}