Pin payments

class pin_payments.refunds.Refunds(api_key: str, mode: str = 'live')

Bases: Base

A class to handle refund operations for payments. This class interacts with an API to manage and retrieve information about refunds. :param api_key: The API key used for authentication. :type api_key: str :param mode: The mode of the API (either ‘live’ or ‘test’). Defaults to ‘live’. :type mode: str

create_refund(charge_token: str, amount: int | None = None) → dict

Creates a refund for a given charge token :param charge_token: The charge token associated with the refund. :type charge_token: str :param amount: The amount to be refunded, if provided. Defaults to None. :type amount: Optional[int] :return: A dictionary containing the details of the created refund. :rtype: dict :raises Exception: If the request fails or returns an error response.

details(refund_token: str) → dict

Retrieves details of a specific refund using the refund token :param refund_token: The token of the refund to retrieve details for. :type refund_token: str :return: A dictionary containing the details of the specified refund. :rtype: dic :raises Exception: If the request fails or returns an error response.

list() → dict

Retrieves a list of all refunds Makes a GET request to the refunds endpoint of the API :return: A dictionary containing the list of refunds. :rtype: dic :raises Exception: If the request fails or returns an error response.

list_charge(charge_token: str) → dict

Retrieves a list of refunds for a specific charge :param charge_token: The charge token for which refunds are being retrieved. :type charge_token: str :return: A dictionary containing the list of refunds for the specified charge. :rtype: dic :raises Exception: If the request fails or returns an error response.

class pin_payments.charges.Charges(api_key: str, mode: str = 'live')

Bases: Base

A class to interact with the Charges API for processing payment card charges. This class provides methods to create, void, capture, list, search, and verify charges. :param api_key: The API key for authentication. :param mode: The mode of operation, either ‘live’ or ‘test’. Default is ‘live’.

capture(charge_token: str) → dict

Captures a previously authorized charge :param charge_token: The token of the charge to be captured. :return: A dictionary containing the capture details.

charge(charge_token: str) → dict

Retrieves the details of a specific charge :param charge_token: The token of the charge to retrieve. :return: A dictionary containing the charge details.

create(email: str, description: str, amount: int, ip_address: str, currency: str | None = None, capture: bool | None = None, reference: str | None = None, metadata: dict | None = None, three_d_secure: dict | None = None, platform_adjustment: dict | None = None, card: dict | None = None, card_token: str | None = None, payment_source_token: str | None = None, customer_token: str | None = None) → dict

Creates a new charge and returns its details This method requires one of the following parameters to be provided: card, card_token, payment_source_token, or customer_token :param email: The email address of the purchaser. :param description: A description of the item purchased. :param amount: The amount to charge in the currency’s base unit. :param ip_address: The IP address of the person submitting the payment. :param currency: The three-character ISO 4217 currency code (optional). :param capture: Whether to immediately capture the charge (optional). :param reference: A custom text string for the customer’s bank statement (optional). :param metadata: Arbitrary key-value data associated with the charge (optional). :param three_d_secure: Information required to enable 3D Secure on payments (optional). :param platform_adjustment: Specify an amount to withhold from the merchant entitlement (optional). :param card: The full details of the payment card to be charged (optional). :param card_token: The token of the card to be charged (optional). :param payment_source_token: The token of the payment source to be charged (optional). :param customer_token: The token of the customer to be charged (optional). :return: A dictionary containing the response details or an error message. :raises ValueError: If more than one payment detail parameter is provided.

list() → dict

Returns a paginated list of all charges :return: A dictionary containing the list of charges.

search(query: str | None = None, start_date: str | None = None, end_date: str | None = None, sort: str | None = None, direction: int | None = None) → dict

Searches for charges based on the provided criteria :param query: Return only charges whose fields match the query (optional). :param start_date: Return only charges created on or after this date (optional). :param end_date: Return only charges created before this date (optional). :param sort: The field used to sort the charges (optional). :param direction: The direction in which to sort the charges (optional). :return: A dictionary containing the search results.

verify(session_token: str) → dict

Verifies the result of a 3D Secure enabled charge :param session_token: The session token for verification. :return: A dictionary containing the verification details.

void(charge_token: str) → dict

Voids a previously authorized charge :param charge_token: The token of the charge to be voided. :return: A dictionary containing the void details.

class pin_payments.apple_pay.ApplePayAPI(api_key: str, mode: str = 'live')

Bases: Base

The Apple Pay API supports Apple Pay integrations via Pin Payments, including managing Apple Pay merchant domains and sessions.

check_host(domain_name: str) → dict

Checks if an Apple Pay domain is registered. :param domain_name: The domain name to check. :return: A dictionary with the domain registration status.

create_certificate() → dict

Creates a new Apple Pay certificate. :return: A dictionary with the certificate details.

create_domain(domain_name: str) → dict

Registers a new domain for Apple Pay. :param domain_name: The fully-qualified domain name to register. :return: A dictionary with the domain details.

create_session(validation_url: str, initiative: str, initiative_context: str) → dict

Creates an Apple Pay session. :param validation_url: The URL provided by the Apple Pay JS API during a payment session. :param initiative: The initiative type (e.g., ‘web’ for web payments). :param initiative_context: The domain name initiating the session. :return: A dictionary with session details.

delete_certificate(certificate_token: str) → dict

Deletes an Apple Pay certificate. :param certificate_token: The token of the certificate to delete. :return: A dictionary confirming the deletion.

delete_domain(domain_token: str) → dict

Deletes a registered Apple Pay domain. :param domain_token: The token of the domain to delete. :return: A dictionary confirming the deletion.

get_certificate(certificate_token: str) → dict

Retrieves details of a specific Apple Pay certificate. :param certificate_token: The token of the certificate to retrieve. :return: A dictionary with the certificate details.

list_certificates() → dict

Retrieves a list of all Apple Pay certificates. :return: A dictionary containing a list of certificates.

list_domains() → dict

Retrieves a list of all registered Apple Pay domains. :return: A dictionary containing a list of domains.

upload_certificate(certificate_pem: str) → dict

Uploads an Apple Pay payment processing certificate. :param certificate_pem: The payment processing certificate in PEM format. :return: A dictionary confirming the upload.

class pin_payments.authorisations.Authorisations(api_key: str, mode: str = 'live')

Bases: Base

The authorisations API allows you to create new payment card authorisations, retrieve details of previous authorisations, void authorisations, and capture authorised funds.

capture_authorisation(auth_token: str, amount: int) → dict

Captures the authorised funds and returns details of the charge.

Parameters:

• auth_token – The token of the authorisation to capture.

• amount – The amount to capture in the currency’s base unit.

Returns:

A dictionary containing the response data.

create_authorisation(email: str, description: str, amount: int, ip_address: str, currency: str = 'AUD', card: dict | None = None, card_token: str | None = None, customer_token: str | None = None, reference: str | None = None, metadata: dict | None = None) → dict

Creates a new authorisation and returns its details.

Parameters:

• email – The email address of the purchaser.

• description – A description of the item purchased.

• amount – The amount to authorise in the currency’s base unit.

• ip_address – The IP address of the person submitting the payment.

• currency – The three-character ISO 4217 currency code.

• card – The full details of the payment card to be authorised.

• card_token – The token of the card to be authorised.

• customer_token – The token of the customer to be authorised.

• reference – A custom text string for the customer’s bank statement.

• metadata – Arbitrary key-value data associated with the authorisation.

Returns:

A dictionary containing the response data.

get_authorisation_details(auth_token: str) → dict

Returns the details of an authorisation.

Parameters:

auth_token – The token of the authorisation to retrieve.

Returns:

A dictionary containing the response data.

list_authorisations() → dict

Returns a paginated list of all authorisations.

Returns:

A dictionary containing the response data.

void_authorisation(auth_token: str) → dict

Voids a previously created authorisation and returns its details.

Parameters:

auth_token – The token of the authorisation to void.

Returns:

A dictionary containing the response data.

class pin_payments.balance.Balance(api_key: str, mode: str = 'live')

Bases: Base

The Balance API allows you to see the current balance of funds in your Pin Payments account.

detail() → dict

Returns the current balance of the Pin Payments account. :return: dict

class pin_payments.bank_accounts.BankAccounts(api_key: str, mode: str = 'live')

Bases: Base

The Bank Accounts API allows for securely storing bank account details in exchange for a bank account token.

create(name: str, bsb: str, number: str, publishable_api_key: str | None = None) → dict

Creates a bank account token and returns its details. :param name: The account holder’s name. :param bsb: The BSB code of the bank account. :param number: The account number of the bank account. :param publishable_api_key: Publishable API key for insecure environments. :return: dict

class pin_payments.cards.Cards(api_key: str, mode: str = 'live')

Bases: Base

The cards API allows you to securely store payment card details in exchange for a card token. This class provides functionality for interacting with the cards API, including storing payment card details, retrieving information about stored cards, and managing card-related operations.

create(number: int, expiry_month: int, expiry_year: int, cvc: int, name: str, address_line1: str, address_city: str, address_country: str, publishable_api_key: str | None = None, address_line2: str | None = None, address_postcode: int | None = None, address_state: str | None = None) → dict

Creates a new payment card and stores it securely This method securely stores the card details provided and returns a card token that can be used for future transactions :param number: The card number (16 digits). :param expiry_month: The expiry month of the card (1-12). :param expiry_year: The expiry year of the card (4 digits). :param cvc: The card’s CVC (3 digits). :param name: The cardholder’s name. :param address_line1: The first line of the cardholder’s address. :param address_city: The city of the cardholder’s address. :param address_country: The country of the cardholder’s address. :param publishable_api_key: An optional publishable API key (if applicable). :param address_line2: An optional second line of the cardholder’s address. :param address_postcode: An optional postcode of the cardholder’s address. :param address_state: An optional state of the cardholder’s address :return: A dictionary containing the response data from the API, including the card token :raises ValueError: If required parameters are missing or invalid.

class pin_payments.customers.Customers(api_key: str, mode: str = 'live')

Bases: Base

Initializes the Customers object with API key and mode :param api_key: The API key for authenticating with the service. :param mode: The mode in which the API operates. Default is ‘live’.

create(email: str, first_name: str | None = None, last_name: str | None = None, phone_number: str | None = None, company: str | None = None, notes: str | None = None, card: dict | None = None, card_token: str | None = None) → dict

Creates a new customer :param email: The customer’s email address. :param first_name: The customer’s first name (optional). :param last_name: The customer’s last name (optional). :param phone_number: The customer’s phone number (optional). :param company: The customer’s company (optional). :param notes: Notes related to the customer (optional). :param card: Card details to associate with the customer (optional). :param card_token: A token representing a pre-existing card to associate with the customer (optional). :return: A dictionary containing the customer details. :raises ValueError: If both card and card_token are provided.

create_card(customer_token: str, number: int | None = None, expiry_month: int | None = None, expiry_year: int | None = None, cvc: int | None = None, name: str | None = None, address_line1: str | None = None, address_city: str | None = None, address_country: str | None = None, publishable_api_key: str | None = None, address_line2: str | None = None, address_postcode: int | None = None, address_state: str | None = None, card_token: str | None = None) → dict

Creates a new card for a customer :param customer_token: The unique identifier of the customer. :param number: The card number (optional). :param expiry_month: The expiry month of the card (optional). :param expiry_year: The expiry year of the card (optional). :param cvc: The card’s CVC code (optional). :param name: The name on the card (optional). :param address_line1: The first line of the address (optional). :param address_city: The city of the address (optional). :param address_country: The country of the address (optional). :param publishable_api_key: The publishable API key (optional). :param address_line2: The second line of the address (optional). :param address_postcode: The postcode of the address (optional). :param address_state: The state of the address (optional). :param card_token: A token for an existing card to associate (optional). :return: A dictionary containing the card details. :raises ValueError: If both card_token and card parameters are provided. :raises ValueError: If required card details are missing.

delete(customer_token: str) → dict

Deletes a customer :param customer_token: The unique identifier of the customer to delete. :return: An empty dictionary if the deletion was successful.

delete_card(customer_token: str, card_token: str) → dict

Deletes a card associated with a customer :param customer_token: The unique identifier of the customer. :param card_token: The token of the card to delete. :return: An empty dictionary if the deletion was successful.

delete_subscriptions(customer_token: str, subscription_token: str) → dict

Deletes a subscription for a specific customer :param customer_token: The unique identifier of the customer. :param subscription_token: The unique identifier of the subscription to delete. :return: An empty dictionary if the deletion was successful.

details(customer_token: str) → dict

Retrieves the details of a specific customer :param customer_token: The unique identifier of the customer. :return: A dictionary containing the customer details.

list() → dict

Lists all customers :return: A dictionary containing the list of customers.

list_cards(customer_token: str) → dict

list_charges(customer_token: str) → dict

Lists all cards associated with a specific customer :param customer_token: The unique identifier of the customer. :return: A dictionary containing the list of cards for the customer.

list_subscriptions(customer_token: str) → dict

Lists all subscriptions for a specific customer :param customer_token: The unique identifier of the customer. :return: A dictionary containing the list of subscriptions for the customer.

update(customer_token: str, email: str | None = None, first_name: str | None = None, last_name: str | None = None, phone_number: str | None = None, company: str | None = None, notes: str | None = None, card: dict | None = None, card_token: str | None = None, primary_card_token: str | None = None) → dict

Updates the details of an existing customer :param customer_token: The unique identifier of the customer to update. :param email: The updated email address (optional). :param first_name: The updated first name (optional). :param last_name: The updated last name (optional). :param phone_number: The updated phone number (optional). :param company: The updated company (optional). :param notes: Updated notes (optional). :param card: Updated card details (optional). :param card_token: The card token to use (optional). :param primary_card_token: The primary card token to update the customer (optional). :return: A dictionary containing the updated customer details. :raises ValueError: If more than one card-related parameter is provided.

class pin_payments.deposits.Deposits(api_key: str, mode: str = 'live')

Bases: Base

A class for interacting with the deposits API. This class provides methods for listing deposits and retrieving details for a specific deposit. :param api_key: The API key to authenticate the requests. :param mode: The environment mode to use (default is ‘live’). Can be ‘live’ or ‘test’.

details(deposit_token: str) → dict

Retrieves the details of a specific deposit This method sends a GET request to retrieve details for a deposit based on the provided deposit token :param deposit_token: The unique identifier of the deposit. :returns: A dictionary containing the details of the deposit. :raises: Raises an exception if the response code is not 200.

list() → dict

Lists all deposits This method sends a GET request to retrieve all deposits :returns: A dictionary containing the list of deposits. :raises: Raises an exception if the response code is not 200.

class pin_payments.files.Files(api_key: str, mode: str = 'live')

Bases: Base

The Files API allows for the management of file uploads, including uploading new files, retrieving details of uploaded files, and deleting files.

delete_file(file_token: str) → Dict[str, Any]

Deletes an uploaded file by its token.

Parameters:

file_token – The token of the file to be deleted.

Returns:

A dictionary confirms the deletion of the file.

get_file_details(file_token: str) → Dict[str, Any]

Retrieves the details of an uploaded file by its token.

Parameters:

file_token – The token of the uploaded file.

Returns:

A dictionary containing the details of the file.

upload_file(file_path: str, purpose: str) → Dict[str, Any]

Uploads a new file and returns its details.

Parameters:

• file_path – Local path to the file to be uploaded.

• purpose – The purpose of the file upload, such as ‘dispute_evidence’.

Returns:

A dictionary containing the details of the uploaded file.

class pin_payments.merchants.Merchants(api_key: str, mode: str = 'live')

Bases: Base

The merchants API allows you to examine merchants you have referred to us. Access requires a partner API key, which is available to approved partners.

create(contact: dict, entity: dict, business: dict, bank_account: dict, director: dict, notes: str | None = None) → dict

Creates a new referred merchant in the system and returns a confirmation.

Parameters:

• contact – Personal details of the user logging into the merchant entity account.

• entity – Legal operating details of the merchant entity.

• business – Business details of the merchant entity.

• bank_account – Full details of the bank account for fund settlement.

• director – Details of a person legally responsible for the merchant entity.

• notes – Additional information to support the merchant’s application.

Returns:

dict

default_settings() → dict

Returns the default settings that will be applied to new merchants referred by you.

Returns:

dict

details(merchant_token: str) → dict

Returns the details of a specified merchant referred by you.

Parameters:

merchant_token – Token of the merchant

Returns:

dict

list() → dict

Returns a paginated list of all the merchants referred by you.

Returns:

dict

class pin_payments.payment_sources.PaymentSources(api_key: str, mode: str = 'live')

Bases: Base

The Payment Sources API allows you to securely store payment source details in exchange for a payment source token. This token can then be used to create a single charge with the charges API.

create_payment_source(source_type: str, source: dict, publishable_api_key: str | None = None) → dict

Securely stores a payment source’s details and returns its token and other information. :param source_type: The payment’s type source to create(e.g., ‘card’, ‘applepay’, ‘googlepay’, ‘network_token’). :param source: A dictionary containing the details of the payment source. :param publishable_api_key: Optional; Your publishable API key if requesting from an insecure environment like a web browser or mobile app. :return: A dictionary with the payment source token and other details.

class pin_payments.disputes.Disputes(api_key: str, mode: str = 'live')

Bases: Base

The disputes API allows you to retrieve details of disputes against your charges and perform actions to either challenge or accept them.

accept_dispute(dispute_token: str) → dict

Accepts a dispute. :param dispute_token: The token of the dispute. :return: dict

get_dispute_activity(dispute_token: str) → dict

Returns the activity feed for a dispute. :param dispute_token: The token of the dispute. :return: dict

get_dispute_details(dispute_token: str) → dict

Returns the details of a dispute. :param dispute_token: The token of the dispute. :return: dict

get_dispute_evidence(dispute_token: str) → dict

Displays current evidence batch for a dispute. :param dispute_token: The token of the dispute. :return: dict

list_disputes(sort: str | None = None, direction: int | None = 1) → dict

Returns a paginated list of all disputes. :param sort: The field used to sort the disputes. :param direction: The direction in which to sort the disputes (1 for ascending or -1 for descending). :return: dict

search_disputes(query: str | None = None, status: str | None = None, sort: str | None = None, direction: int | None = 1) → dict

Returns a paginated list of disputes matching the search criteria. :param query: Query for searching disputes. :param status: The status of the disputes. :param sort: The field used to sort the disputes. :param direction: The direction of sorting. :return: dict

submit_dispute_evidence(dispute_token: str) → dict

Submits current evidence batch for review. :param dispute_token: The token of the dispute. :return: dict

update_dispute_evidence(dispute_token: str, evidence_data: dict[str, str]) → dict

Updates evidence batch for a dispute. :param dispute_token: The token of the dispute. :param evidence_data: The evidence data to be updated. :return: dict

class pin_payments.recipients.Recipients(api_key: str, mode: str = 'live')

Bases: Base

The Recipients API allows you to store transfer recipient details and retrieve a token that you can safely store in your application. You can send funds to recipients using the transfer API.

create(email: str, name: str | None = None, bank_account: dict | None = None, bank_account_token: str | None = None) → dict

Creates a new recipient and returns its details.

Parameters:

• email – The email address of the recipient.

• name – A name for this recipient.

• bank_account – The full details of the bank account to be stored.

• bank_account_token – The token of the bank account to be stored.

Returns:

dict

get_details(recipient_token: str) → dict

Returns the details of a recipient.

Parameters:

recipient_token – Your recipient token.

Returns:

dict

list() → dict

Returns a paginated list of all recipients.

Returns:

dict

list_transfers(recipient_token: str) → dict

Returns a paginated list of a recipient’s transfers.

Parameters:

recipient_token – Your recipient token.

Returns:

dict

update(recipient_token: str, email: str | None = None, bank_account: dict | None = None, bank_account_token: str | None = None) → dict

Updates the details of a recipient and returns its new details.

Parameters:

• recipient_token – Your recipient token.

• email – The email address of the recipient.

• bank_account – The full details of the bank account to be stored.

• bank_account_token – The token of the bank account to be stored.

Returns:

dict

class pin_payments.subscriptions.Subscriptions(api_key: str, mode: str = 'live')

Bases: Base

The Subscriptions API allows managing subscriptions against plans, including creating new subscriptions, retrieving details of existing subscriptions, updating, reactivating, and cancelling subscriptions, and fetching subscription ledger entries.

cancel_subscription(sub_token: str) → dict

Cancels the subscription identified by subscription token. :param sub_token: The token of the subscription. :return: A dictionary containing the response data.

create_subscription(plan_token: str, customer_token: str, include_setup_fee: bool = True) → dict

Activates a new subscription and returns its details. :param plan_token: The token of the plan to subscribe to. :param customer_token: The token of the customer to be subscribed. :param include_setup_fee: Whether the setup fee should be applied. :return: A dictionary containing the response data.

fetch_subscription_ledger(sub_token: str) → dict

Fetches the ledger entries relating to a subscription. :param sub_token: The token of the subscription. :return: A dictionary containing the response data.

get_subscription_details(sub_token: str) → dict

Returns the details of the subscription identified by subscription token. :param sub_token: The token of the subscription. :return: A dictionary containing the response data.

list_subscriptions() → dict

Returns a paginated list of all subscriptions. :return: A dictionary containing the response data.

reactivate_subscription(sub_token: str, include_setup_fee: bool = True) → dict

Reactivates the subscription identified by subscription token. :param sub_token: The token of the subscription. :param include_setup_fee: Whether the setup fee should be applied. :return: A dictionary containing the response data.

update_subscription(sub_token: str, card_token: str | None = None) → dict

Updates the card associated with a subscription. :param sub_token: The token of the subscription. :param card_token: The token of the new card to associate with the subscription. :return: A dictionary containing the response data.

class pin_payments.transfers.Transfers(api_key: str, mode: str = 'live')

Bases: Base

The transfers API allows you to send money to Australian bank accounts and retrieve details of previous transfers.

create(description: str, amount: int, currency: str, recipient: str) → dict

Creates a new transfer and returns its details.

Parameters:

• description – A description of the amount being transferred.

• amount – The amount to transfer in the currency’s base unit.

• currency – The currency to transfer.

• recipient – The recipient’s token or ‘self’ for an own account.

Returns:

dict

details(transfer_token: str) → dict

Returns the details of the specified transfer.

Parameters:

transfer_token – Token of the transfer.

Returns:

dict

line_items(transfer_token: str) → dict

Returns a paginated list of line items associated with the specified transfer.

Parameters:

transfer_token – Token of the transfer.

Returns:

dict

list() → dict

Returns a paginated list of all transfers.

Returns:

dict

search(query: str | None = None, start_date: str | None = None, end_date: str | None = None, sort: str | None = None, direction: int | None = None) → dict

Returns a paginated list of transfers matching the search criteria.

Parameters:

• query – Search query.

• start_date – Start date for filtering.

• end_date – End date for filtering.

• sort – Field to sort by.

• direction – Sort direction.

Returns:

dict