API

Our API uses JSON, so you need to include the following header in all your requests:

Content-Type: application/json

Authentication

To authenticate your requests, you must include the following header:

Authorization: Bearer {secret_token}

It is mandatory to use https, to avoid sending your credentials in clear text through the web. If you don't, you will be redirected to the https version of Apurata, but your credentials will have already been compromised on the web.

Register voucher

Register a voucher with referential information to do the match. Some fields may change during the process of validation, so be careful.

URL: https://apurata.com/apagos/unchecked_payment/register

METHOD: POST

Auth required : Yes

Data constraints

Ideally this amount should be the same as in the receipt. But we tolerate errors in this field, thus, it is referential for us. In the success response, the amount field may be different from the amount you send here if the receipt image had a different amount.

Format: YYYY-MM-DD

Ideally this date should be the same as in the receipt. But we tolerate errors in this field, thus, it is referential for us. In the success response, the date field may be different from the date you send here if the receipt image had a different date.

Ideally this operation number should be the same as in the receipt. But we tolerate errors in this field, thus, it is referential for us. Also, the bank usually have a different operation number in your historic movements. For that reason, this operation number can be changed during the process of validation.

Must match one of the accounts provided on the onboarding. This field can be changed if the receipt image does not correspond to the account provided.

Must be unique per voucher, it is assigned by you, aPagos don't use this field, we just pass it back to you. You should use this field to identify the payment.

Where aPagos make the callback request when a payment is validated or invalidated.

URL to a public image. The supported formats are jpeg, png, gif, bmp, webp, raw, ico, pdf, and tiff. If the receipt is not in any of these formats, we invalidate automatically the voucher.

Help humans identify the payment. We show it in the dashboard.

Include fields for extra functionality. You can ignore this field unless you have some very specific needs.

Success Response

Unique id assigned by apurata to each request to identify the results when calling the webhook callback. It is the string representation of an ObjectId.

Example response

{
    "request_id": "601e8d0d4e5f4000201a3a33"
}

Error Responses

In case of invalid JSON or invalid data in some field:

Code: 400 BAD REQUEST
Content: A string describing the error

In case of invalid or misconfigured authentication:

Code: 401 UNATHORIZED

Notes

Some fields may change during the process of validation, so be careful.

Example CURL

curl 'https://apurata.com/apagos/unchecked_payment/register' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {secret_token}' \
    --data-raw $'{
        "amount": 123.30,
        "order_id": "1001",
        "operation_number": "696",
        "bank_account_id": "BBVA",
        "date": "2020-10-30",
        "webhook": "https://3f5c6c449e2208bbe977709b902b742c.m.pipedream.net",
        "receipt": "https://img.freepik.com/free-vector/realistic-receipt-template_23-2147938550.jpg",
        "detail": "testing INVALID request",
        "customer_dni": "12345678",
        "customer_fullname": "Juan Pérez Aguilar"
    }'

Example response

{
    "request_id": "5fd165ea0f08d78a6937980e"
}

Cancel a payment

Change the payment status to CANCELED. In case it has already been associated with a transaction, release said transaction so that it can be associated with another payment.

URL: https://apurata.com/apagos/unchecked_payment/cancel/{request_id}

METHOD: POST

Auth required : Yes

Data constraints

The status you believe the payment is into. If this status does not match with the real status, an error will be returned and the cancellation will fail.

Success Response

Wether the voucher was canceled or not, it should always be true.

Example response

{
    "canceled": true
}

Error responses

In case there is not any voucher with the given request id:

Code: 404 NOT FOUND

In case of invalid or misconfigured authentication:

Code: 401 UNATHORIZED

In case the actual status is not equal to the expected_status sent in the request:

Code: 400 BAD REQUEST

It includes a JSON body with the following fields:

Wether the voucher was canceled or not, it should always be false.

For now we have just one error code: "invalid_status"

A human readable text explaining the error

The actual status of the voucher, so you can resend your request.

Example response

{
    canceled: false,
    error_code: "invalid_status",
    error_detail: "The payment was expected to be in status {expected_status} but was in status {status}"
    extra_data: {
        status: "PENDING"|"VALIDATED"|"INVALID"
    }
}

Example CURL

curl 'https://apurata.com/apagos/unchecked_payment/cancel/{request_id}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {secret_token}' \
    --data-raw $'{
        "expected_status": "PENDING"
    }'

Get voucher status

Get a voucher information. Some fields may have changed during the process of validation, so be careful.

URL: https://apurata.com/apagos/unchecked_payment/info/{request_id}

METHOD: GET

Auth required : Yes

Data constraints

It is returned by aPagos when the voucher is registered. It is the string representation of an objectId.

Success Response

On success, the voucher information is returned with the following fields:

Same as in the query param.

Amount used to match the voucher with the bank information. It can be different from what was provided when registering the payment.

Format: YYYY-MM-DD

Date used to match the voucher with the bank information. It can be different from what was provided when registering the payment.

Operation number used to match the voucher with the bank information. It can be different from what was provided when registering the payment.

Must match one of the accounts provided on the onboarding. This field can be different from what was provided when registering the payment.

Must be unique per voucher, it is assigned by you, aPagos don't use this field, we just pass it back to you. You should use this field to identify the payment.

Help humans identify the payment. We show it in the dashboard.

Either "VALIDATED" or "INVALID". Indicates if the payment was validated or it is invalid.

In case the voucher is validated; the amount, date, bank_account_id and operation_number fields contain the right information, that is not necessarily the same that was provided when registering the voucher.

The operation number that the bank uses in their historic records. We scraped this number from your bank account.

Example response

{
    "order_id": "1001",
    "status": "VALIDATED",
    "bank_account_id": "BBVA",
    "operation_number": "696",
    "amount": 123.30,
    "bank_operation_number": "00010696",
    "detail": "Some info about the payment",
    "date": "2020-10-30",
    "request_id": "5fd166272826d9992620d028"
  }

Error Responses

In case there is not any voucher with the given request id:

Code: 404 NOT FOUND

In case of invalid or misconfigured authentication:

Code: 401 UNATHORIZED

Notes

The amount, date, bank_account_id and operation_number fields contain the right information, that is not necessarily the same that was provided when registering the voucher.

Example CURL

curl 'https://apurata.com/apagos/unchecked_payment/info/{request_id}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {secret_token}'