This library provides a pure Python interface to the Spreedly REST APIs.
The easiest way to install the latest version is by using pip/easy_install to pull it from Github:
$ pip install git+https://github.com/yousifa/spreedly-sdk
$ easy_install git+https://github.com/yousifa/spreedly-sdk
You may also use Git to clone the repository from Github and install it manually:
$ git clone https://github.com/yousifa/spreedly-sdk
$ python setup.py install
import spreedly_sdk as spreedly
client = spreedly.Client(ENVIRONMENT_KEY, ACCESS_SECRET)
To use Spreedly Core you have to have at least one gateway. You can create a test gateway, by default .
client.gateway()
{
'characteristics': {
'supports_3dsecure_authorize': True,
'supports_3dsecure_purchase': True,
'supports_authorize': True,
'supports_capture': True,
'supports_credit': True,
'supports_offsite_authorize': True,
'supports_offsite_purchase': True,
'supports_purchase': True,
'supports_purchase_via_preauthorization': True,
'supports_reference_authorization': True,
'supports_reference_purchase': True,
'supports_remove': True,
'supports_store': True,
'supports_void': True
},
'created_at': datetime.datetime(2014, 5, 25, 0, 30, 45),
'credentials': None,
'gateway_specific_fields': None,
'gateway_type': 'test',
'name': 'Spreedly Test',
'payment_methods': {
'payment_method': [
'credit_card',
'sprel',
'third_party_token',
'bank_account'
]
},
'redacted': False,
'state': 'retained',
'token': 'U2JKWnRYIsNKWfta9kITRUbci0j',
'updated_at': datetime.datetime(2014, 5, 25, 0, 30, 45)
}
Each gateway type has a different set of credentials needed to communicate with it and are only available in some countries.
client.gateway(gateway_type, **credential_data)
gateway_token = 'U2JKWnRYIsNKWfta9kITRUbci0j'
client.get_gateway(gateway_token)
client.get_gateway_list()
client.get_gateway_list(since_token=gateway_token)
If you create a gateway using a normal authenticated add gateway api call, the gateway is automatically retained.
If a gateway is created using an unauthenticated channel such as client-side scripting, it is kept in a cached state until it is retained or automatically redacted. This allows your customers to create gateways using their own credentials, but until you retain it, it cannot be used and you will not be billed for it.
client.retain(gateway_token)
Gateways can't be deleted (since they're permanently associated with any transactions run against them), but the sensitive credential information in them can be redacted so that they're inactive:
client.redact(gateway_token)
A credit card can be tokenized for future transactions.
# Tokenize card info
tokenized_card = client.tokenize_credit_card(
first_name="Homer",
last_name="Simpson",
number="5555555555554444",
verification_value="123",
month="01",
year="2022",
email="doh@homersimpson.com",
retained=True,
eligible_for_card_updater=False)
# Get payment token if transaction is successful
payment_method_token = ''
if tokenized_card["transaction"]["succeeded"] is True:
payment_method_token = tokenized_card["transaction"]["payment_method"]["token"]
A bank account can be tokenized for future transactions.
# Tokenize bank info
tokenized_bank = client.tokenize_bank(
first_name="Homer",
last_name="Simpson",
bank_routing_number="021000021",
bank_account_number="9876543210",
retained=True
)
# Get payment token if transaction is successful
payment_method_token = ''
if tokenized_bank["transaction"]["succeeded"] is True:
payment_method_token = tokenized_bank["transaction"]["payment_method"]["token"]
A purchase call immediately takes funds from the payment method (assuming the transaction succeeds).
payment_method_token = 'CwhkxFxm5nzn3cts4t7TzasgWBl'
client.purchase(100, 'EUR', payment_method_token, gateway_token)
{
'amount': 100,
'api_urls': None,
'created_at': datetime.datetime(2014, 5, 25, 1, 9, 43),
'currency_code': 'EUR',
'description': None,
'email': None,
'gateway_specific_fields': None,
'gateway_specific_response_fields': None,
'gateway_token': 'VacV0dCGUwU2Ydu0IZOBzFHxQQN',
'gateway_transaction_id': '64',
'ip': None,
'merchant_location_descriptor': None,
'merchant_name_descriptor': None,
'message': {
'messages.transaction_succeeded': 'Succeeded!'
},
'on_test_gateway': True,
'order_id': None,
'payment_method': {
'address1': None,
'address2': None,
'card_type': 'visa',
'city': None,
'country': None,
'created_at': datetime.datetime(2014, 5, 25, 1, 8, 45),
'data': None,
'email': None,
'errors': None,
'first_name': 'Smith',
'first_six_digits': '411111',
'full_name': 'Smith Smith',
'last_four_digits': '1111',
'last_name': 'Smith',
'month': 12,
'number': 'XXXX-XXXX-XXXX-1111',
'payment_method_type': 'credit_card',
'phone_number': None,
'state': None,
'storage_state': 'used',
'test': True,
'token': 'CwhkxFxm5nzn3cts4t7TzasgWBl',
'updated_at': datetime.datetime(2014, 5, 25, 1, 9, 43),
'verification_value': None,
'year': 2017,
'zip': None
},
'response': {
'avs_code': None,
'avs_message': None,
'cancelled': False,
'created_at': datetime.datetime(2014, 5, 25, 1, 9, 43),
'cvv_code': None,
'cvv_message': None,
'error_code': None,
'error_detail': None,
'message': 'Successful purchase',
'pending': False,
'success': True,
'updated_at': datetime.datetime(2014, 5, 25, 1, 9, 43)
},
'state': 'succeeded',
'succeeded': True,
'token': '8qge2CZBikhXr44c6vi1tqvjFVw',
'transaction_type': 'Purchase',
'updated_at': datetime.datetime(2014, 5, 25, 1, 9, 43)
}
If the purchase or authorize is successful, you may then want to retain the payment method. Passing the retain_on_success parameter to the purchase or authorize call can save you from having to make another API call to do the retain. If the purchase or authorize succeeds, then the payment method is retained for you.
client.purchase(100, 'EUR', payment_method_token, gateway_token, retain_on_success=True)
Some gateways require some of their customers to submit a CVV value for all of their transactions. If you're one of the very few customers who can't seem to convince your gateway to remove the CVV requirement, reference transactions may help. And in some cases, using reference transactions can lower decline rates.
transaction_token = '8qge2CZBikhXr44c6vi1tqvjFVw'
client.reference(100, 'EUR', payment_method_token, transaction_token)
{
'amount': 100,
'api_urls': None,
'created_at': datetime.datetime(2014, 5, 25, 1, 13, 29),
'currency_code': 'EUR',
'description': None,
'email': None,
'gateway_specific_fields': None,
'gateway_specific_response_fields': None,
'gateway_token': 'VacV0dCGUwU2Ydu0IZOBzFHxQQN',
'gateway_transaction_id': '61',
'ip': None,
'merchant_location_descriptor': None,
'merchant_name_descriptor': None,
'message': {
'messages.transaction_succeeded': 'Succeeded!'
},
'on_test_gateway': True,
'order_id': None,
'reference_token': '8qge2CZBikhXr44c6vi1tqvjFVw',
'response': {
'avs_code': None,
'avs_message': None,
'cancelled': False,
'created_at': datetime.datetime(2014, 5, 25, 1, 13, 29),
'cvv_code': None,
'cvv_message': None,
'error_code': None,
'error_detail': None,
'message': 'Successful purchase',
'pending': False,
'success': True,
'updated_at': datetime.datetime(2014, 5, 25, 1, 13, 29)
},
'state': 'succeeded',
'succeeded': True,
'token': 'Xgv6FUCtMIFNhj8n5ibZCuEXldV',
'transaction_type': 'PurchaseViaReference',
'updated_at': datetime.datetime(2014, 5, 25, 1, 13, 29)
}
An authorize works just like a purchase; the difference being that it doesn't actually take the funds. NOTE: authorize will hold funds on some payment methods, notably debit cards.
client.authorize(100, 'EUR', payment_method_token, gateway_token)
{
...
'transaction_type': 'Authorization'
...
}
A capture will actually take the funds previously reserved via an authorization.
client.capture(transaction_token)
Void is used to cancel out authorizations and, with some gateways, to cancel actual payment transactions within the first 24 hours (credits are used after that; see below).
client.void(transaction_token)
A credit is like a void, except it actually reverses a charge instead of just canceling a charge that hasn't yet been made. It's a refund.
client.credit(transaction_token)
A particular transaction.
client.get_transaction(transaction_token)
The details of the transactions for your account.
client.get_transaction_list()
client.get_transaction_list(since_token=transaction_token)
The details of the transactions for a payment method.
client.get_payment_method_transaction_list(payment_method_token)
client.get_payment_method_transaction_list(payment_method_token, since_token=transaction_token)
The details of the transactions for a gateway.
client.get_gateway_transaction_list(gateway_token)
client.get_gateway_transaction_list(gateway_token, since_token=transaction_token)