Card Collection

Initiate

This API method initiates a collection/purchase request and returns a JSON response.

POST {base url}/api/v1/purchases/

Headers

Name

Type

Description

Authorization*

Bearer {{secret key}}

Content-Type*

String

application/json

{
"client": {
    "email": "[email protected]",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}",
}

{
  "client": {
    "client_type": null,
    "email": "[email protected]",
    "phone": "0793457034",
    "full_name": "Example One",
    "personal_code": "123245",
    "legal_name": "",
    "brand_name": "",
    "registration_number": "",
    "tax_number": "",
    "bank_account": "",
    "bank_code": "234235",
    "street_address": "sixth street",
    "city": "Lisbon",
    "zip_code": "3425678",
    "country": "AU",
    "state": "PT",
    "shipping_street_address": "",
    "shipping_city": "",
    "shipping_zip_code": "",
    "shipping_country": "",
    "shipping_state": "",
    "cc": [],
    "bcc": [],
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ]
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000,
        "quantity": "1.0000",
        "discount": 0,
        "tax_percent": "0.00",
        "category": ""
      }
    ],
    "language": "en",
    "notes": "",
    "debt": 0,
    "subtotal_override": null,
    "total_tax_override": null,
    "total_discount_override": null,
    "total_override": null,
    "total": 1000,
    "request_client_details": [],
    "timezone": "UTC",
    "due_strict": false,
    "email_message": "",
    "shipping_options": [],
    "payment_method_details": {},
    "has_upsell_products": false
  },
  "payment": null,
  "issuer_details": {
    "brand_name": "PAYTOTA",
    "website": "https://paytota.com",
    "legal_name": "PAYTOTA",
    "registration_number": "80020002500244",
    "tax_number": "",
    "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi",
    "legal_country": "UG",
    "legal_city": "Kamplaa",
    "legal_zip_code": "23235",
    "bank_accounts": [
      {
        "bank_account": "1036201557307",
        "bank_code": "EQBLUGKAXXX"
      }
    ]
  },
  "transaction_data": {
    "payment_method": "",
    "flow": "payform",
    "extra": {},
    "country": "",
    "attempts": []
  },
  "status": "created",
  "status_history": [
    {
      "status": "created",
      "timestamp": 1687258526
    }
  ],
  "viewed_on": null,
  "force_recurring": false,
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "is_test": false,
  "user_id": null,
  "brand_id": "edd6c020-eac6-4b4e-9716-47928f3401d1",
  "billing_template_id": null,
  "order_id": null,
  "client_id": "dfb1fb80-0322-4daa-900f-b0a39cda0450",
  "send_receipt": false,
  "is_recurring_token": false,
  "recurring_token": null,
  "skip_capture": false,
  "reference_generated": "PT213",
  "reference": "",
  "issued": "2023-06-20",
  "due": 1687262125,
  "refund_availability": "none",
  "refundable_amount": 0,
  "currency_conversion": null,
  "payment_method_whitelist": null,
  "success_redirect": "",
  "failure_redirect": "",
  "cancel_redirect": "",
  "success_callback": "",
  "marked_as_paid": false,
  "upsell_campaigns": [],
  "referral_campaign_id": null,
  "referral_code": null,
  "referral_code_details": null,
  "referral_code_generated": null,
  "retain_level_details": null,
  "can_retrieve": false,
  "can_chargeback": false,
  "creator_agent": "",
  "platform": "api",
  "product": "purchases",
  "created_from_ip": "102.218.37.140",
  "invoice_url": null,
  "checkout_url": "https://payments.paytota.com/p/9fd05d5c-6639-42f4-8189-a6f9e401988f/",
  "direct_post_url": null,
  "created_on": 1687258526,
  "updated_on": 1687258526,
  "type": "purchase",
  "id": "9fd05d5c-6639-42f4-8189-a6f9e401988f"
}

curl --location --globoff '{{base_url}}/api/v1/purchases/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Secret Key}}' \
--data-raw '{
"client": {
    "email": "[email protected]",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{{base_url}}/api/v1/purchases/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
"client": {
    "email": "[email protected]",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
    },
"purchase": {
    "currency": "USD",
    "products": [{
        "name": "test",
        "price": 1000
    }]
    },
"skip_capture": false,
"brand_id": "{{Brand Id}}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {{Secret Key}}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const axios = require('axios');
let data = JSON.stringify({
  "client": {
    "email": "[email protected]",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000
      }
    ]
  },
  "skip_capture": false,
  "brand_id": "{{Brand Id}}"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{base_url}}/api/v1/purchases/',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{Secret Key}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

import http.client
import json

conn = http.client.HTTPSConnection("{{base_url}}")
payload = json.dumps({
  "client": {
    "email": "[email protected]",
    "country": "AU",
    "city": "Lisbon",
    "street_address": "sixth street",
    "zip_code": "3425678",
    "state": "PT"
  },
  "purchase": {
    "currency": "USD",
    "products": [
      {
        "name": "test",
        "price": 1000
      }
    ]
  },
  "skip_capture": False,
  "brand_id": "{{Brand Id}}"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{Secret Key}}'
}
conn.request("POST", "/api/v1/purchases/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

You have two methods to collect card details from the customer .

Redirect the customer to the {{checkout_url}} on the paytota platform.
Direct Post. Here you submit the customer card details from your application to the {{checkout_url}} . In this case the customer will be redirected to the bank authorization page immediately. Take note the following parameters should be added to your Initial JSON body on using Direct Post success_redirect, failure_redirectAfter the payment is processed, the system will redirect the customer back to your website.

 <!DOCTYPE html>
<html>
   <head>
      <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8">
   </head>
   <body>
      <form id="form" action="{{checkout_url}}" method="POST">
         <input type="hidden" name="cardholder_name" value="Asiman Gasanov">
            <input type="hidden" name="card_number" value="4444 3333 2222 1111">
            <input type="hidden" name="expires" value="11/25">
            <input type="hidden" name="cvc" value="123">
            <input type="hidden" name="remember_card" value="true">
            <noscript>
            <input type="submit" name="continue" value="Continue">
            </noscript>
      </form>
   </body>
</html>

Testing Integration

It’s possible to test-drive all checkouts using a test Purchase. - 4444 3333 2222 1111 - non-3D Secure card - 5555 5555 5555 4444 - 3D Secure card For both cards, please use: - any cardholder name - any expiry larger or equal to the current month/year - CVC = 123 For a failed payment, please change the CVC or expiration date

You will receive a callback on your webhook URL regarding the status of the transaction

Successful transaction  (status = paid)
Failed transaction (status = error)

Callback Example

{
  "id": "761196a9-6aa2-4afd-a59f-214ad6788e5e",
  "due": 1694609579,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "London",
    "email": "[email protected]",
    "phone": "+447702700000",
    "state": "WA",
    "country": "US",
    "zip_code": "CT6 6HG",
    "bank_code": "",
    "full_name": "John Deo",
    "brand_name": "",
    "legal_name": "",
    "tax_number": "",
    "client_type": null,
    "bank_account": "",
    "personal_code": "",
    "shipping_city": "",
    "shipping_state": "",
    "street_address": "39 coromant way",
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ],
    "shipping_country": "",
    "shipping_zip_code": "",
    "registration_number": "",
    "shipping_street_address": ""
  },
  "issued": "2023-09-13",
  "status": "paid",
  "is_test": false,
  "payment": {
    "amount": 2300,
    "paid_on": 1694606029,
    "currency": "USD",
    "fee_amount": 150,
    "net_amount": 2150,
    "description": "",
    "is_outgoing": false,
    "payment_type": "purchase",
    "pending_amount": 0,
    "remote_paid_on": 1694606028,
    "owned_bank_code": null,
    "owned_bank_account": null,
    "pending_unfreeze_on": null,
    "owned_bank_account_id": null
  },
  "product": "purchases",
  "user_id": null,
  "brand_id": "869aca7c-6348-4c5f-9141-6f9e908da099",
  "order_id": null,
  "platform": "api",
  "purchase": {
    "debt": 0,
    "notes": "",
    "total": 2300,
    "currency": "USD",
    "language": "en",
    "products": [
      {
        "name": "deposit",
        "price": 2300,
        "category": "",
        "discount": 0,
        "quantity": "1.0000",
        "tax_percent": "0.00"
      }
    ],
    "timezone": "UTC",
    "due_strict": false,
    "email_message": "",
    "total_override": null,
    "shipping_options": [],
    "subtotal_override": null,
    "total_tax_override": null,
    "has_upsell_products": false,
    "payment_method_details": {},
    "request_client_details": [],
    "total_discount_override": null
  },
  "client_id": "70a626d4-b415-46b9-9dda-89e37ebdf1d4",
  "reference": "325408517",
  "viewed_on": null,
  "company_id": "177bde08-d0a3-47b0-9601-7fec23b8d4fb",
  "created_on": 1694605979,
  "event_type": "purchase.paid",
  "updated_on": 1694606029,
  "invoice_url": null,
  "can_retrieve": true,
  "checkout_url": "https://gate.paytota.com/p/761196a9-6aa2-4afd-a59f-214ad6788e5e/invoice/",
  "send_receipt": false,
  "skip_capture": false,
  "creator_agent": "",
  "referral_code": null,
  "can_chargeback": true,
  "issuer_details": {
    "website": "",
    "brand_name": "PAYTOTA LIMITED",
    "legal_city": "Kampala",
    "legal_name": "PAYTOTA LIMITED",
    "tax_number": "",
    "bank_accounts": [
      {
        "bank_code": "Will send",
        "bank_account": "Will send"
      }
    ],
    "legal_country": "UG",
    "legal_zip_code": "102145",
    "registration_number": "80020002500244",
    "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi"
  },
  "marked_as_paid": false,
  "status_history": [
    {
      "status": "created",
      "timestamp": 1694605979
    },
    {
      "status": "pending_execute",
      "timestamp": 1694605986
    },
    {
      "status": "paid",
      "timestamp": 1694606029
    }
  ],
  "cancel_redirect": "https://example.com/1B7fCk992UZVAbWngU0j7-w",
  "created_from_ip": "85.208.60.10",
  "direct_post_url": null,
  "force_recurring": false,
  "recurring_token": null,
  "failure_redirect": "https://example.com/1jkfljS8Uxa-dNEGkPHLbsQ",
  "success_callback": "https://example.com/0bCCbefX4Bi-4JXjpgB5Qpw",
  "success_redirect": "https://example.com/1ulvVG6sAKQEUkDvKDRBX6w",
  "transaction_data": {
    "flow": "direct_post",
    "extra": {
      "card_type": "debit",
      "card_brand": "mastercard",
      "masked_pan": "537410******0294",
      "card_issuer": "national westminster bank plc",
      "expiry_year": 26,
      "expiry_month": 12,
      "cardholder_name": "Ryan lee",
      "card_issuer_country": "GB"
    },
    "country": "GB",
    "attempts": [
      {
        "flow": "direct_post",
        "type": "execute",
        "error": null,
        "extra": {
          "card_type": "debit",
          "card_brand": "mastercard",
          "masked_pan": "537410******0294",
          "card_issuer": "national westminster bank plc",
          "expiry_year": 26,
          "expiry_month": 12,
          "cardholder_name": "Jon Deo",
          "card_issuer_country": "GB"
        },
        "country": "GB",
        "client_ip": "84.70.164.234",
        "fee_amount": 150,
        "successful": true,
        "payment_method": "mastercard",
        "processing_time": 1694606028
      }
    ],
    "payment_method": "mastercard"
  },
  "upsell_campaigns": [],
  "refundable_amount": 2300,
  "is_recurring_token": false,
  "billing_template_id": null,
  "currency_conversion": null,
  "reference_generated": "PT159",
  "refund_availability": "all",
  "referral_campaign_id": null,
  "retain_level_details": null,
  "referral_code_details": null,
  "referral_code_generated": null,
  "payment_method_whitelist": null
}

Check Collection/Purchase Status

This method is used to query the collections/purchases transaction status using the transaction ID. Please note that this API also requires authorization using the Secret Key.

GET {base url}/api/v1/purchases/{id}/

Headers

Name

Type

Description

Content-Type*

String

application/json

Authorization*

String

Bearer {{secret key}}

PreviousCARDS NextBank

Last updated 1 year ago

{ "id": "761196a9-6aa2-4afd-a59f-214ad6788e5e", "due": 1694609579, "type": "purchase", "client": { "cc": [], "bcc": [], "city": "London", "email": "[email protected]", "phone": "+447702700000", "state": "WA", "country": "US", "zip_code": "CT6 6HG", "bank_code": "", "full_name": "John Deo", "brand_name": "", "legal_name": "", "tax_number": "", "client_type": null, "bank_account": "", "personal_code": "", "shipping_city": "", "shipping_state": "", "street_address": "39 coromant way", "delivery_methods": [ { "method": "email", "options": {} }, { "method": "text_message", "options": { "custom_message": "" } } ], "shipping_country": "", "shipping_zip_code": "", "registration_number": "", "shipping_street_address": "" }, "issued": "2023-09-13", "status": "paid", "is_test": false, "payment": { "amount": 2300, "paid_on": 1694606029, "currency": "USD", "fee_amount": 150, "net_amount": 2150, "description": "", "is_outgoing": false, "payment_type": "purchase", "pending_amount": 0, "remote_paid_on": 1694606028, "owned_bank_code": null, "owned_bank_account": null, "pending_unfreeze_on": null, "owned_bank_account_id": null }, "product": "purchases", "user_id": null, "brand_id": "869aca7c-6348-4c5f-9141-6f9e908da099", "order_id": null, "platform": "api", "purchase": { "debt": 0, "notes": "", "total": 2300, "currency": "USD", "language": "en", "products": [ { "name": "deposit", "price": 2300, "category": "", "discount": 0, "quantity": "1.0000", "tax_percent": "0.00" } ], "timezone": "UTC", "due_strict": false, "email_message": "", "total_override": null, "shipping_options": [], "subtotal_override": null, "total_tax_override": null, "has_upsell_products": false, "payment_method_details": {}, "request_client_details": [], "total_discount_override": null }, "client_id": "70a626d4-b415-46b9-9dda-89e37ebdf1d4", "reference": "325408517", "viewed_on": null, "company_id": "177bde08-d0a3-47b0-9601-7fec23b8d4fb", "created_on": 1694605979, "event_type": "purchase.paid", "updated_on": 1694606029, "invoice_url": null, "can_retrieve": true, "checkout_url": "https://gate.paytota.com/p/761196a9-6aa2-4afd-a59f-214ad6788e5e/invoice/", "send_receipt": false, "skip_capture": false, "creator_agent": "", "referral_code": null, "can_chargeback": true, "issuer_details": { "website": "", "brand_name": "PAYTOTA LIMITED", "legal_city": "Kampala", "legal_name": "PAYTOTA LIMITED", "tax_number": "", "bank_accounts": [ { "bank_code": "Will send", "bank_account": "Will send" } ], "legal_country": "UG", "legal_zip_code": "102145", "registration_number": "80020002500244", "legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi" }, "marked_as_paid": false, "status_history": [ { "status": "created", "timestamp": 1694605979 }, { "status": "pending_execute", "timestamp": 1694605986 }, { "status": "paid", "timestamp": 1694606029 } ], "cancel_redirect": "https://example.com/1B7fCk992UZVAbWngU0j7-w", "created_from_ip": "85.208.60.10", "direct_post_url": null, "force_recurring": false, "recurring_token": null, "failure_redirect": "https://example.com/1jkfljS8Uxa-dNEGkPHLbsQ", "success_callback": "https://example.com/0bCCbefX4Bi-4JXjpgB5Qpw", "success_redirect": "https://example.com/1ulvVG6sAKQEUkDvKDRBX6w", "transaction_data": { "flow": "direct_post", "extra": { "card_type": "debit", "card_brand": "mastercard", "masked_pan": "537410******0294", "card_issuer": "national westminster bank plc", "expiry_year": 26, "expiry_month": 12, "cardholder_name": "Ryan lee", "card_issuer_country": "GB" }, "country": "GB", "attempts": [ { "flow": "direct_post", "type": "execute", "error": null, "extra": { "card_type": "debit", "card_brand": "mastercard", "masked_pan": "537410******0294", "card_issuer": "national westminster bank plc", "expiry_year": 26, "expiry_month": 12, "cardholder_name": "Jon Deo", "card_issuer_country": "GB" }, "country": "GB", "client_ip": "84.70.164.234", "fee_amount": 150, "successful": true, "payment_method": "mastercard", "processing_time": 1694606028 } ], "payment_method": "mastercard" }, "upsell_campaigns": [], "refundable_amount": 2300, "is_recurring_token": false, "billing_template_id": null, "currency_conversion": null, "reference_generated": "PT159", "refund_availability": "all", "referral_campaign_id": null, "retain_level_details": null, "referral_code_details": null, "referral_code_generated": null, "payment_method_whitelist": null }

hashtagInitiate

hashtagThis API method initiates a collection/purchase request and returns a JSON response.

hashtagHeaders

hashtagYou have two methods to collect card details from the customer .

hashtagTesting Integration

hashtagCheck Collection/Purchase Status

hashtagThis method is used to query the collections/purchases transaction status using the transaction ID. Please note that this API also requires authorization using the Secret Key.

hashtagHeaders

Initiate

This API method initiates a collection/purchase request and returns a JSON response.

Headers

You have two methods to collect card details from the customer .

Testing Integration

Check Collection/Purchase Status

This method is used to query the collections/purchases transaction status using the transaction ID. Please note that this API also requires authorization using the Secret Key.

Headers