Accept or Reject Deposit Endpoint

This API gives you the functionality to either accept or decline a deposit that has been received, based on the account details

You can utilize the same headers and logic found on our technical and security aspects page.

Before utilizing any of our APIs, you should contact your responsible account manager, with your company's name and CNPJ so we can make the necessary configurations for you to proceed.

Decline or Accept an incoming deposit

POST https://api-stg.onekeypayments.com/v3/{deposit_id}/{status} This endpoint allows you to accept or decline a payment, based on the details received on a deposit. By utilizing the deposit_id field, to identify the transaction, we can use APPROVE in status to accept the transaction or REJECT in case you want to reject the payment.

Example deposit creation request:

{
    "invoice_id": "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "[e-mail]",
        "phone": "[phone]",
        "address": {
            "street": "Rua 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "registration_date": "20220914",
    "bank_accounts": [
          {
              "account_number": "12345"
              "ispb_code": 60746948
              "bank_code": 502
              "bank_branch": "90"
          },
           {
              "account_number": "67890"
              "ispb_code": 60742938
              "bank_code": 502
              "bank_branch": "80"
          }
   ]
  },
    "payment_method": "IX",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.onekeypayments.com/deposit_cancelled",
    "success_url": "https://www.onekeypayments.com/deposit_completed",
    "error_url": "https://www.onekeypayments.com/deposit_error",
    "notification_url": "https://www.onekeypayments.com/okp/notify",
    "logo": "https://www.onekeypayments.com/onekeypayments.png",
    "test": true,
    "mobile": false,
    "language": "pt"
}

In this example deposit, we've received 2 bank accounts from the customer: Agencia (branch): 90 Account: 12345 Agencia (branch): 80 Account: 67890

Please note that everything within the "bank_accounts" object is sent from your side - This can also be sent empty, and we would await your response for these cases.

Example of a matching deposit check status response:

{
    "user_id": "11",
    "deposit_id": 300004285,
    "invoice_id": "989409592",
    "country": "BR",
    "currency": "BRL",
    "local_amount": 53162.00,
    "usd_amount": 1000.00,
    "bonus_amount": 1.50,
    "bonus_relative": "false",
    "payment_method": "IX",
    "status": "PENDING",
    "payer": {
        "document": "17532655253",
        "document_type": "CPF",
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Smith",
        "address": {
            "city": "Sao Paulo",
            "state": "SP",
            "street": "John Street 2453",
            "zip_code": "938475-234"
        }
    },
    "fee_amount": 2.50,
    "fee_currency": "USD",
    "bank_account": { 
        "account_number": "12345", 
        "bank_branch": "90", 
        "ispb_code": 60746948,
        "bank_name": "Caixa",
        "account_type": "SAVING"
}

In this response, we can see that the payer used an account with the bank_branch: 90 and the account_number: 12345, so we can confirm that it matches with the previously registered bank account(s) from the customer, so you can proceed with the approval.

Approve

POST https://api-stg.onekeypayments.com/v3/300004285/APPROVE

After using this endpoint, the funds are released to the customer, and the transaction status is changed to COMPLETED.

Example of a non-matching deposit check status response:

{
    "user_id": "11",
    "deposit_id": 300004285,
    "invoice_id": "989409592",
    "country": "BR",
    "currency": "BRL",
    "local_amount": 53162.00,
    "usd_amount": 1000.00,
    "bonus_amount": 1.50,
    "bonus_relative": "false",
    "payment_method": "IX",
    "status": "PENDING",
    "payer": {
        "document": "17532655253",
        "document_type": "CPF",
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Smith",
        "address": {
            "city": "Sao Paulo",
            "state": "SP",
            "street": "John Street 2453",
            "zip_code": "938475-234"
        }
    },
    "fee_amount": 2.50,
    "fee_currency": "USD",
    "bank_account": { 
        "account_number": "88888", 
        "bank_branch": "20", 
        "ispb_code": 60746948,
        "bank_name": "Caixa",
        "account_type": "SAVING"
}

In this example, we can see that the account_number received from the payer's bank does not match the initial request, so you can proceed with the rejection of this transaction:

Reject

POST https://api-stg.onekeypayments.com/v3/300004285/REJECT

After utilizing this endpoint, the deposit changes its status to EXPIRED, and the funds are returned back to the payer's account.