NAV Navbar
cURL C#
  • Introduction
  • Payment
  • Tokenization
  • Appendix
  • Errors
  • Introduction

    Welcome to the official documentation for SWAPPT API. We have put a lot of effort in this documentation to make it as slick and as usable as possible. Let us walk you through it and let us know if you have any questions at any time.

    We also have Swagger, a platform to test our API. Check it out!
    https://api.swappt.com/swagger

    SWAPPT API is a REST API that has an HTTP POST method for each operation. It is composed of three primary processes:

    Endpoints

    The endpoints for each operation follow the same structure:

    EXAMPLE: Let's say that you belong to the organisation named "test" and you wish to use the version 1 of the SWAPPT API to make a payment. Your request would be the following:

    POST https://api.swappt.com/v1/organizations/test/payment

    POST https://api.swappt.com/v<VERSION_ID>/organizations/<ORGANIZATION_ID>/<OPERATION>

    Parameter Description
    VERSION_ID API Version.
    ORGANIZATION_ID Your identifier as organization (that you will get when live).
    operation The operation to realize.

    Authentication

    curl https://api.swappt.com/v1/organizations/test/payment \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json"
    
    using (var content = new StringContent(rq, System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/payment");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    You need to authenticate when performing an API method. Moreover, the API will perform authorization in each and every method call, please make sure that you have thr necessary permissions to call the required method.

    To authenticate, you need to place the word ApiKey followed by your API key on the Authorization header of your HTTP request.

    API Flow

    To adjust to our customers' needs, we offer several possibilities as to API usage:

    To perform fraud analysis:

    Use the Payment method by filling in the fraud_process information during the request. The application will then return an answer.

    To perform a payment:

    The first step is to retrieve all payment methods available. To do so, we will use the method AvailablePaymentMethods. This method will return all the available payment methods according to the configuration set on the platform.

    This list will be shown to the final customer in order to allow the choosing of the payment method. Once the customer selects a payment method, the Payment method must be called. This method will carry out the fraud analysis (if specified). To call thi method, the information returned in the response of the AvailablePaymentMethods method is required.

    Depending on the method of payment selected it will be necessary to proceed in the following ways:

    Widget Pay

    Widget Pay is a JavaScript code that, inserted on your website, will prevent you to touch sensible data by encrypting it on the client side. To use it, you only need to follow the next steps:

    1· Place a form named card-form in your page. It has to have the following fields:

    HTML valid form example:

        <form id="card-form">
            <label for="card-element">Credit or debit card</label>
            <input type="text" id="card-number" name="card-number" placeholder="XXXX XXXX XXXX XXXX" required>
            <input type="text" id="card-month" name="card-month" placeholder="MM" required>
            <input type="text" id="card-year" name="card-year" placeholder="YY" required>
            <input type="text" id="card-cvv" name="card-cvv" placeholder="CVV" required>
            <button id="card-button">SUBMIT</button>
        </form>
    
    Field name Field description
    card-number Card number.
    card-month Card expiration month.
    card-year Card expiration year.
    card-cvv Card security code.

    Class Card definition example:

    var Card = (function() {
      function Card(number, expiration_month, expiration_year, security_code) {
        this.number = number;
        this.expiration_month = expiration_month;
        this.expiration_year = expiration_year;
        this.security_code = security_code;
      }
      return Card;
    })();
    

    2· Define the class Card with the following structure:

    Field name Field description
    number Card number.
    month Card expiration month.
    year Card expiration year.
    cvv Card security code.

    3· To encrypt the data, you must add a listener on the button, create a Card object, and call the encryption library:

    (function() { document.getElementById("card-button").addEventListener("click", function() { event.preventDefault(); var number = document.getElementById("card-number").value; var month = document.getElementById("card-month").value; var year = document.getElementById("card-year").value; var cvv = document.getElementById("card-cvv").value; var card = new Card(number, month, year, cvv); var publicKey = -----BEGIN PUBLIC KEY----- YOUR PUBLIC KEY -----END PUBLIC KEY-----; var encrypt = new JSEncrypt(); encrypt.setPublicKey(publicKey); var encrypted = encrypt.encrypt(JSON.stringify(card)); }); })();

    4· Then, it is necessary to clean the form and insert the resultant string in a hidden input.

    function saveCard(encrypted) { var form = document.getElementById("card-form"); form.reset(); var hiddenInput = document.createElement("input"); hiddenInput.setAttribute("type", "hidden"); hiddenInput.setAttribute("name", "card-token"); hiddenInput.setAttribute("value", encrypted); form.appendChild(hiddenInput); }

    5· Use the generated string!

    Payment

    AvailablePaymentMethods

    AvailablePaymentMethods request example

    curl https://api.swappt.com/v1/organizations/test/available_payment_methods \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "currency_amount": { ... },
                "departure": "2017-08-08T10:50",
                "cancellation_expenses_beginning": "2017-08-08T10:50",
                "excluded_methods": [ "Undefined" ],
                "only_secure_payment": true,
                "session_code": "string",
                "global_configuration": {
                  "my_config_key_1": "my_value1"      
                }
            }'
    
    AvailablePaymentMethodsRQ rq = new AvailablePaymentMethodsRQ 
    {
      currencyAmount = new CurrencyAmont { ... },
      departure = "2017-08-08T10:50",
      cancellationExpensesBeginning = "2017-08-08T10:50",
      excludedMethods: new PaymentMethodType[] { Enums.PaymentMethodType.Visa, Enums.PaymentMethodType.Paypal },
      onlySecurePayment = true,
      sessionCode = "string",
      globalConfiguration = new Dictionary<string, string> { {"my_config_key_1", "my_value1"} },
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/available_payment_methods");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    The available_payment_methods is the first method that needs to be executed. With this method, you will get the list of payment methods available for the transaction and the configuration specified.

    AvailablePaymentMethodsRQ

    AvailablePaymentMethodsRQ example

    {
        "currency_amount" : { ... },
        "departure" : "2017-08-08T10:50",
        "cancellation_expenses_beginning" : "2017-08-08T10:50",
        "excluded_methods" : [
            "Undefined"
        ],
        "only_secure_payment" : true,
        "session_code" : "string",
        "global_configuration" : {
            "my_config_key_1" : "my_value1"
        }
    }
    
    Attribute Type Description
    currency_amount CurrencyAmount Payment base amount where taxes will be applied. The `CurrencyAmount specifies the amount and the currency used for this payment. The currency code must be specified in ISO3 (ISO 4217)) format.
    departure DateTime Departure Date (UTC).
    cancellation_expenses_beginning DateTime When the purchase will have cancellation expenses.
    excluded_methods Array[String(PaymentMethodType)] List of payment methods to ignore.
    fraud_information FraudInformation This node can indicate previous fraud information so only secure gateways are returned.
    only_secure_payment Boolean To force the application return a secure gateway.
    session_code String Identifies the transactions of the same session.
    global_configuration Key-Value Configuration to determine the results.

    CurrencyAmount

    CurrencyAmount example

    {
        "amount": 8.95,
        "currency_code": "EUR"
    }
    
    Attribute Type
    amount Integer
    currency_code String

    AvailablePaymentMethodsRS

    AvailablePaymentMethodsRS example

    {
        "payment_methods" : [ ... ],
        "status" : "Success"
    }
    
    Attribute Type Description
    payment_methods Array[AvailablePaymentMethod] List of available payment methods.
    status String(EndTransactionType) Identifies if any processing error has occurred.

    AvailablePaymentMethod

    AvailablePaymentMethod example

    {
        "type" : "Undefined",
        "reference_token" : "string",
        "amount_total" : 0,
        "currency" : "string",
        "overcost_amount" : 0,
        "overcost_percentage" : 0,
        "overcost_currency" : "string",
        "gateway_code" : "string",
        "is_3ds" : true,
        "paypal_token" : "string",
        "offline_transference_list" : [ ... ]
    }
    
    Attribute Type Description
    type String(PaymentMethodType) Payment method name.
    reference_token String Token generated during the search. It is necessary for the next flow method.
    amount_total Decimal Total amount with overcosts and fees added.
    overcost_amount Decimal Total overcost amount.
    overcost_percentage Decimal Percentage overcost.
    overcost_currency String Overcost currency. Must be specified in ISO3 (ISO 4217)) format.
    gateway_code String Gateway wich the payment will be proceded.
    is_3ds Boolean Identifies if thegateway is 3ds or not.
    paypal_token String PayPal token if method type is PayPal.
    offline_transference_list Array[OfflineTransference] The list of the offline transference payment types avaliable.

    OfflineTransference

    OfflineTransference example

    {
        "bank_id" : "string",
        "bank_description" : "string",
        "bank_name" : "string",
        "beneficiary" : "string",
        "iban" : "string",
        "swift" : "string"
    }
    
    Attribute Type Description
    bank_id String Bank identifier.
    bank_description String Bank description.
    bank_name String Bank name.
    beneficiary String Beneficiary.
    iban String IBAN.
    swift String SWIFT.

    Process

    Process request example

    curl https://api.swappt.com/v1/organizations/test/payment \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "card_data" : { ... },
                "card_type" : "Explicit",
                "merchant_reference" : "string",
                "currency_amount" : { ... },
                "sender_details" : { ... },
                "items_details" : [{ ... }],            
                "session_code" : "string",
                "payment_method" : "Undefined",
                "fraud_process" : { ... },
                "payment_process" : { ... },
                "global_configuration": {
                  "my_config_key_1": "my_value1"      
                }
              }'
    
    ProcessRQ rq = new ProcessRQ 
    {
      cardData = new CardData { ... },
      cardType = Enums.CardType.Explicit,
      merchant_reference = "string", 
      currency_amount = new CurrencyAmount { ... },
      sender_details = new SenderDetails { ... },
      items_details = new List<ItemsDetails>() { new ItemsDetails{ ... } },
      session_code = "string", 
      payment_method = Enums.PaymentMethodType.Undefined,
      fraud_process = new FraudProcess { ... },
      payment_process = new PaymentProcess { ... },
      globalConfiguration = new Dictionary<string, string> { {"my_config_key_1", "my_value1"} },
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/payment");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    The main process where a payment and/or fraud analysis is complete (if SWAPPT Switcher and/or SWAPPT FDS solutions are hired and activated). It requires only two calls for the SWAPPT API to execute a payment: Get Available Payment Methods, and Payment. More actions can be done related to the payment process, a Payment Details method to retrieve the status and details of a payment, and a Refund method to refund a payment.

    As previously mentioned, the Payment procedure is intended to do the main payment process and/or do a previous Fraud analysis. The request must have the following JSON structure:

    ProcessRQ

    Process request example

    {
        "card_data" : { ... },
        "card_type" : "Explicit",
        "merchant_reference" : "string",
        "currency_amount" : { ... },
        "sender_details" : { ... },
        "items_details" : [{ ... }],            
        "session_code" : "string",
        "payment_method" : "Undefined",
        "fraud_process" : { ... },
        "payment_process" : { ... },
        "global_configuration": {
          "my_config_key_1": "my_value1"      
        }
    }
    
    Attribute Type Description
    card_data CardData Card data information.
    card_type String(CardInfoType) Used to determine the mandatory format of card_data field.
    merchant_reference String Merchant's transaction reference.
    currency_amount CurrencyAmount Currency of the payment
    sender_details SenderDetails Buyer information
    items_details Array(ItemDetail) Payment breakdown in items.
    session_code String Identifies the transactions of the same session.
    payment_method String(PaymentMethodType) Payment method.
    fraud_process FraudProcessRQ Needed if you want to perform a fraud analysis.
    payment_process PaymentProcessRQ Needed if you want to make a payment.
    global_configuration String Key - String Value Dynamic configuration data.

    CardData:

    CardData example

    {
        "store_card_info" : true,
        "number" : "1111111111111111",
        "expiration_month" : 4,
        "expiration_year" : 2035,
        "security_code" : "000"
    }
    
    Attribute Type Description
    encrypted_data Boolean Card data information encrypted by the SWAPPT CSE JavaScript. Mandatory if card_type is Encrypted.
    store_card_info String Indicates whether if the information is necessary stored and tokenize for future uses by the SWAPPT Vault service.
    tokenized_data String Token pointing the data previously stored on SWAPPT Vault. Mandatory if card_type is Tokenized.
    number String Card number. Mandatory if card_type is Explicit.
    expiration_month Integer Card expiration month. Mandatory if card_type is Explicit.
    expiration_year Integer Card expiration year. Mandatory if card_type is Explicit.
    security_code String Card security code. Mandatory if card_type is Explicit.

    SenderDetails:

    SenderDetails example

    {
        "holder" : "string",
        "id" : "string",
        "name" : "string",
        "surname" : "string",
        "email" : "string",
        "phone_number" : "string",
        "ssn" : "string",
        "address" : { ... },
        "billing_address" : { ... },
        "sender_bank_details" : { ... },
        "recipient_bank_details" : { ... }
    }
    
    Attribute Type Description
    holder String Holder name and surname.
    id String Transaction's sender id.
    name String Sender name.
    surname String Sender surname.
    email String Sender email.
    phone_number String Sender phone number.
    ssn String Social Security Number.
    address Address Sender address.
    billing_address Address Billing address.
    sender_bank_details BankDetails BankDetails Sender bank details.
    recipient_bank_details BankDetails Recipent bank details.

    Address:

    Address example

    {
        "country_code" : "string",
        "city" : "string",
        "address_line1" : "string",
        "address_line2" : "string",
        "zip_code" : "00000"
    }
    
    Attribute Type Description
    country_code String Country code in ISO3 (ISO 4217) format.
    city String City name.
    address_line1 String Address line 1 (main).
    address_line2 String Address line 2 (additional information).
    zip_code String Adress zip code.

    BankDetails:

    BankDetails example

    {
        "bic" : "string",
        "holder" : "string",
        "bank_account" : { ... },
        "bank_name" : "string",
        "country_code" : "string",
        "iban" : "string"
    }
    
    Attribute Type Description
    bic String BIC.
    holder String Bank holder.
    bank_account BankAccount Bank account data.
    bank_name String Bank name.
    country_code String Bank country code in ISO3 (ISO 4217) format.
    iban String IBAN.

    BankAccount:

    BankAccount example

    {
        "number" : "string",
        "security_code" : "string"
    }
    
    Attribute Type Description
    number String Bank account's numbers.
    security_code String Bank account security code.

    ItemDetail:

    ItemDetail example

    {
      "id": "0",
      "name": "string",
      "description": "string",
      "item_date" : { ... },
      "quantity": 1,
      "currency_amount" : { ... },
      "other_amount" : { ... },
      "image_url": "string",
      "provider": "string"
    }
    
    Attribute Type Description
    id String Item ID.
    name String Item name.
    description String Item description.
    item_date ItemDate Item's date information.
    quantity String Item quantity.
    currency_amount CurrencyAmount Currency of the payment
    other_amount CurrencyAmountExtended Currency of the payment
    image_url String Item image url.
    provider String Item's provider.

    CurrencyAmountExtended

    CurrencyAmountExtended example

    {
        "type": "GiftCard",
        "amount": 8.95,
        "currency_code": "EUR"
    }
    

    FraudProcessRQ

    FraudProcessRQ example

        "rules_module" : [ ... ],
        "default_result" : "string",
        "silent_tools": [ "Sift_science" ]
        "device_fingerprint" : "string",
        "ip_address" : "string",
        "session_id" : "string",
        "custom_data" : {
            "ToolCode" : { ... } 
        }
    }
    
    Attribute Type Description
    rules_module Array[FraudRule] Array of Fraud rules to be applied (if no rules specified, it will be used the configured ones on the SWAPPT FDS's website.
    default_result String The result that must be returned if no rule is triggered (mandatory if rules provided on the request). Values can be Undefined, Accept, Reject or AcceptWithSecurePayment.
    silent_tools Array[String(ToolCode)] The tools placed in this list will be analyzed and its result will be returned, even if its decision is not relevant for the FDS's decision.
    device_fingerprint String Customer’s device ID.
    ip_address String Customer’s IP Address.
    session_id String Customer’s navigation session ID.
    custom_data Key ToolName - Value Object Additional data that Fraud should know. The values are objects with information about the transaction and it only should be indicated to a unique tool.

    * Protect: Key-Value containing the Custom Fields of the transaction, where Key is the Custom Field name, and Value it’s value (Custom Fields must be previously configured con SWAPPT Protect’s website).
    * Sift_science: Comming soon.

    FraudRule:

    FraudRule example

    {
        "modules" : { 
          "module_key" : { ... }
        },
        "global_decision" : "Reject",
        "priority" : 3
    }
    
    Attribute Type Description
    modules Key-Value The combination of results that the tools should return. Key: String(ToolCode) Value: Module
    global_decision String(GlobalDecision) The result that FDS must return if this rule triggers.
    priority Integer The priority of this rule (the more greater value the more priority)

    Module:

    Module example

    {
      "module_type": "ByScoring",
      "min_scoring": 65,
      "max_scoring": 80
    }
    
    Attribute Type Description
    module_type String(ModuleType) Tells if the rule is based in a decision or in a score.
    decision_type String(ModuleDecision) The tool's resulting decision.
    min_scoring Integer Lower score value range.
    max_scoring Integer Higher score value range.

    PaymentProcessRQ:

    PaymentProcessRQ example

    {                             
      "source" : { ... },    
      "gateway_code" : "string"  ,
      "reference_token" : "string",
      "payment_details" : { ... } ,
      "callback_url_fail" : "string",
      "callback_url_success" : "string",
    }
    
    Attribute Type Description
    source Source Transaction's agency origin.
    gateway_code String Gateway identifier code.
    reference_token String This token was returned by AvailablePaymentMethods call. When the customer chose an available payment method you should send here the chosen token.
    payment_details PaymentDetails Information about the payment.
    callback_url_fail String Url to return after a failed gateway process.
    callback_url_success String Url to return after a success gateway process.

    PaymentDetails:

    PaymentDetails example

    {                             
      "amount": 8.95,
      "currency": "EUR",
      "reasons": [ ... ],
      "booking_reference": "string",
      "num_installments": 0,
      "agency_code_partner": "string",
      "language_code": "string"
    }
    
    Attribute Type Description
    amount Integer Payment amount.
    currency String Payment amount currency.
    reasons Array[Reason] Payment breakdown in reasons format (mandatory).
    booking_reference String Merchant locator reference.
    num_installments String Number of installments.
    agency_code_partner String Partner agency code.
    language_code String Language code.

    Reason:

    Reason example

    {                             
      "id": "string",
      "content": "string"
    }
    
    Attribute Type Description
    id Integer Reason id
    content String Reason explanation.

    Source:

    Source example

    {                             
      "country_code": "string",
      "agency_code": "string"
    }
    
    Attribute Type Description
    country_code String Country code in ISO 3 (ISO 4217) format.
    agency_code String Agency code.

    ProcessRS

    ProcessRS example

    {
      "fraud_response": { ...  },
      "payment_response": { ... },
      "card_data_token": "string",
      "status": "Success"
    }
    
    Attribute Type Description
    fraud_response FraudProcessRS FDS result information.
    payment_response PaymentProcessRS Switcher response.
    card_data_token String Card token (for future uses).
    status String(EndTransactionType) Response status.

    FraudProcessRS

    FraudProcessRS example

    {
      "result" : "Undefined",
      "toolsResults" : {
          "ToolCode" : { ... } 
      }
    }
    
    Attribute Type Description
    result String(GlobalDecision) FDS's final result.
    toolsResults Key-Value A Key-Value containing the responses of the tools that did an analysis, where Key: String(ToolCode), Value: Object (see Fraud Tools responses appendix section for more details).

    PaymentProcessRS

    PaymentProcessRS example

    {
      "transaction" : { ... },
      "redirect" : { ... }
    }
    
    Attribute Type Description
    transaction PaymentTransaction Information about the transaction done.
    redirect Redirect Redirect information.

    PaymentTransaction

    PaymentTransaction example

    {
      "id" : "string",
      "type" : "Expirable",
      "expiration_datetime" : "2017-08-07T13:36:10.057Z",
      "transaction_datetime" : "2017-08-07T13:36:10.057Z",
      "currency_amount" : { ... },
      "status" : "Success",
      "status_description" : "string",
      "pending_reason" : "PendingCredit",
      "payment_method" : "Mastercard"
    }
    
    Attribute Type Description
    id String Transaction id.
    type String(TransactionType) Transaction type (Final/Expirable).
    expiration_datetime String Transaction's expiration date.
    transaction_datetime String When the transaction was done.
    currency_amount CurrencyAmount Transaction's amount.
    status String(TransactionStatus) Transaction's status.
    status_description String More info about the transaction's status.
    pending_reason String(PendingReason) Why the transaction is pending.
    payment_method String(PaymentMethodType) Transaction's payment method.

    Redirect

    Redirect example

    {
      "method": "string",
      "protocol": "string",
      "form_input": [ ... ]
    }
    
    Attribute Type Description
    method String Http method.
    protocol String Network protocol.
    form_inputs FormInput Inputs to add to the redirect method.

    FormInput

    FormInput example

    {
      "key": "string",
      "value": "string"
    }
    
    Attribute Type Description
    key String Input key.
    value String Input Value.

    Payment Details

    Payment details request example

    curl https://api.swappt.com/v1/organizations/test/details \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "search_type" : "ByDates",
                "transaction_start_time" : "2017-08-10T07:49:05.089Z",
                "transaction_end_time" : "2017-08-10T07:49:05.089Z",
                "session_code" : "string",
                "source" : { ... },
                "merchant_reference" : "string",
                "gateway_code": "string"
            }'
    
    DetailsRQ rq = new DetailsRQ 
    {
      searchType = Enums.SearchType.ByTransaction,
      transactionID = "string",
      transactionStartTime = null,
      transactionEndTime = null,
      sessionCode = "string",
      source = new Source { ... },
      merchantReference = "string",
      gatewayCode = "string"
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/details");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    The Payment Details call returns the information related to a payment. It is really useful to check the status of a payment after the payment call.

    PaymentDetailsRQ

    PaymentDetailsRQ

    {
      "search_type": "ByDates",
      "transaction_start_time": "2017-08-10T07:49:05.089Z",
      "transaction_end_time": "2017-08-10T07:49:05.089Z",
      "session_code": "string",
      "source": { ... },
      "merchant_reference": "string",
      "gateway_code": "string"
    }
    
    Attribute Type Description
    search_type String Indicates the type of search that wants to be done.
    transaction_id String Transaction id (only when ByTransaction searches)
    transaction_start_time String Search start date (only when ByDates searches)
    transaction_end_time String Search end date (only when ByDates searches)
    session_code string Identifies the transactions of the same session.
    source Source Transaction's agency origin.
    merchant_reference string Merchant's transaction reference.
    gateway_code String Indicates the code of the gateway where the payment details should be consulted.

    PaymentDetailsRS

    PaymentDetailsRS

    {
      "transactions": [ ... ],
      "redirect": { ... },
      "status": "Success"
    }
    
    Attribute Type Description
    transactions Array[DetailsTransaction] Details of every transaction involving this payment.
    redirect String Redirect information.
    status String Response status.

    DetailsTransaction

    DetailsTransaction

    {
      "id": "string",
      "type": "Expirable",
      "expiration_datetime": "2017-08-10T07:49:05.086Z",
      "status": "Unknown",
      "status_description": "string",
      "currency_amount": { ... },
      "pending_reason": "Unknown",
      "payment_method": "Undefined",
      "transaction_datetime": "2017-08-10T07:49:05.086Z",
      "refund_reasons": [ ... ],
      "refunded_currency_amount": { ... }
    }
    
    Attribute Type Description
    id String Transaction id.
    type String(TransactionType) Transaction type (Final/Expirable).
    expiration_datetime String Transaction's expiration date.
    transaction_datetime String When the transaction was done.
    currency_amount CurrencyAmount Transaction's amount.
    status String String(TransactionStatus)
    status_description String More info about the transaction's status.
    pending_reason String(PendingReason) Transaction's reason to be pending.
    payment_method String(PaymentMethodType) Transaction's payment method.
    refund_reasons Array[Reason] Refund reasons.
    refunded_currency_amount CurrencyAmount If a refund was done, the amount that was refunded.

    Refund Payment

    Payment Refund request example

    curl https://api.swappt.com/v1/organizations/test/refund \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "transaction_id": "string",
                "currency_amount": { ... },
                "sender": { ... },
                "reasons": [ ... ],
                "agency_code_partner": "string",
                "session_code": "string",
                "source": { ... },
                "merchant_reference": "string",
                "gateway_code": "string"
            }'
    
    RefundRQ rq = new RefundRQ
    {
      transactionID = "string",
      currencyAmount = new CurrencyAmount { ... },
      sender = new SenderDetails { ... },
      reasons = new Reason [] [ { ... } ],
      agencyCodePartner = "string",
      sessionCode = "string",
      source = new Source { ... },
      merchantReference = "string",
      gatewayCode = "string"
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/refund");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    With a refund call, it is possible to ask the refund of a payment.

    PaymentRefundRQ

    PaymentRefundRQ

    {
      "transaction_id": "string",
      "currency_amount": { ... },
      "sender": { ... },
      "reasons": [ ... ],
      "agency_code_partner": "string",
      "session_code": "string",
      "source": { ... },
      "merchant_reference": "string",
      "gateway_code": "string"
    }
    
    Attribute Type Description
    transaction_id String Transaction id.
    currency_amount CurrencyAmount Amount to be refunded.
    sender_details SenderDetails Buyer's information.
    reasons Array[Reason] The reasons for the refund.
    agency_code_partner String Partner agency code.
    session_code string Identifies the transactions of the same session.
    source Source Transaction's agency origin.
    merchant_reference string Merchant's transaction reference.
    gateway_code String Indicates the code of the gateway where the payment details should be consulted.

    PaymentRefundRS

    PaymentRefundRS

    {
      "transactions": [ ... ],
      "redirect": { ... },
      "status": "Success"
    }
    
    Attribute Type Description
    transactions Array[DetailsTransaction] Information bout the transaction done.
    redirect String Redirect information.
    status String(EndTransactionType) Response status.

    Feed fraud

    There exist fraud tools with machine learning strategy and this tools need to be notified about how the payment has been finished. We have divided this notifications in two different types: Events and decisions.

    FeedEventRQ

    Feed event request example

    curl https://api.swappt.com/v1/organizations/test/feed/events \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "merchant_reference" : "string",
                "sender_details" : { ... },
                "currency_amount" : { ... },
                "payment_method" : "Undefined",
                "global_configuration" : {
                  "my_config_key_1":  "my_value1"
                },
                "target_tools" : [
                    "Undefined"
                ],
                "custom_data" : { ... },
                "session_code" : "string"
              }'
    
    FeedEventRQ rq = new FeedEventRQ 
    {
      merchant_reference = "string", 
      sender_details = new SenderDetails { ... },
      currency_amount = new CurrencyAmount { ... },
      payment_method = Enums.PaymentMethodType.Undefined,
      globalConfiguration = new Dicctionary<string, string> { {"my_config_key_1", "my_value1"} },
      target_tools = new PaymentMethodType[] { Enums.PaymentMethodType.Undefined }, 
      session_code = "string", 
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/events");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    Events : It is something that can happens with a payment Ex: The payment received a chargeback, a cancellation or just received a notification about a success payment.

    Attribute Type Description
    merchant_reference String Merchant's transaction reference.
    sender_details SenderDetails Buyer information
    currency_amount CurrencyAmount Currency of the payment
    payment_method String(PaymentMethodType) Payment method.
    global_configuration String Key - String Value Dynamic configuration data.
    target_tools Array([PaymentMethodType]) List of tools that will be notified.
    session_code String Identifies the transactions of the same session.

    FeedDecision

    Feed decision request example

    curl https://api.swappt.com/v1/organizations/test/feed/decisions \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "decision" : { ... }
                "merchant_reference" : "string",
                "sender_details" : { ... },
                "currency_amount" : { ... },
                "payment_method" : "Undefined",
                "global_configuration" : {
                  "my_config_key_1":  "my_value1"
                },
                "target_tools" : [
                    "Undefined"
                ],
                "custom_data" : { ... },
                "session_code" : "string"
              }'
    
    FeedEventRQ rq = new FeedEventRQ 
    {
      decision = new Decision { ... },
      merchant_reference = "string", 
      sender_details = new SenderDetails { ... },
      currency_amount = new CurrencyAmount { ... },
      payment_method = Enums.PaymentMethodType.Undefined,
      globalConfiguration = new Dicctionary<string, string> { {"my_config_key_1", "my_value1"} },
      target_tools = new PaymentMethodType[] { Enums.PaymentMethodType.Undefined }, 
      session_code = "string", 
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/decisions");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    Decisions: It is a decision that you can take about a payment. Ex: If your owns system decides automatically mark the payment as fraudulent, you must notify all the providers about this decision.

    Attribute Type Description
    decision Decision Information about the decision taken.
    merchant_reference String Merchant's transaction reference.
    sender_details SenderDetails Buyer information
    currency_amount CurrencyAmount Currency of the payment
    payment_method String(PaymentMethodType) Payment method.
    global_configuration String Key - String Value Dynamic configuration data.
    target_tools Array([PaymentMethodType]) List of tools that will be notified.
    session_code String Identifies the transactions of the same session.

    Decision

    Decision example

        "description": "string",
        "trigger": "manual",
        "type": "bad",
        "analyst": "string",
        "id": "string",
        "user_id": "string",
        "is_bad": true,
        "reasons": [
          {
            "id": "string",
            "content": "string"
          }
        ]
    }
    
    Attribute Type Description
    description String Description about why this decision was taken.
    trigger String(TriggerType) How this decision was taken.
    type String(DecisionType) Indicate why the decision was taken.
    analyst String If the trigger type is "manual" this field will specify who applied this decision.
    id String Decision id. For some tool it should be specified.
    user_id String Id of the user who the decision applies. It only need to be specified if the decision is about a customer.
    is_bad Boolean Indicate if the decision is a negative for the paymennt.
    reasons Array[Reason] Reasons of why this decision has been chosen.

    Feed responses

    PaymentRefundRS

    {
      "status": "Success"
    }
    

    The response is the same for both types (decisions & events). The response information returned is a field with an estatus.

    Attribute Type Description
    status String(EndTransactionType) Response status.

    Tokenization

    SWAPPT's Vault solution core process. As you may know, this process is used to tokenize and retrieve credit cards.

    Tokenize

    Tokenize request example

    curl https://api.swappt.com/v1/organizations/test/tokenize \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "credit_card": { ... },
                "meta_data": {
                  "client_name":"name"
                }
              }'
    
    TokenizeRQ rq = new TokenizeRQ 
    {
      creditCard = new CreditCard { ... },
      metaData = { {"client_name", "name"} }
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/tokenize");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    SWAPPT Vault’s tokenization is used to tokenize credit cards. The system will save that information, and will return a unique token. The structure of the body must match the following:

    TokenizeRQ

    TokenizeRQ example

    {
      "credit_card": { ... },
      "meta_data": {
        "client_name":"name"
      }
    }
    
    Attribute Type Description
    credit_card CreditCardData Credit card raw data.
    meta_data Key-Value Optional meta-data that wants to be added to the card (More information below).

    CreditCardData

    CreditCardData example

        "number": "1111111111111111",
        "expiration_month": 4,
        "expiration_year": 2035,
        "security_code": "000"
    }
    
    Attribute Type Description
    number String Card number.
    expiration_month Integer Card expiration month.
    expiration_year Integer Card expiration year.
    security_code String Card security code.

    TokenizeRS

    TokenizeRS example

    {
      "token": "K7WMBFTB5VAQPJWVHBZLFQWCPAYQAQWWS5U4F4NS6MKN4LWDX74EVRZLUOQS6FQOQKXHIXTY2WXH2===",
      "status": "Success"
    }
    
    Attribute Type Description
    token String Generated card data token.
    status String(EndTransactionType) Response status.

    Where status takes the values Success or Error. If Success, token contains the unique token, if Error, error_details contains information related to the error occurred (see Appendix's section ) for a deep description). Note that the token returned has 1 unique use. When used, the system will provide a new one (if desired), and will make the used one useless.

    Retrieve

    Retrieve request example

    curl https://api.swappt.com/v1/organizations/test/retrieve \
         -H "Authorization: ApiKey YourApiKey" \
         -H "Content-type: application/json" \
         -d  '{
                "token": "K7WMBFTB5VAQPJWVHBZLFQWCPAYQAQWWS5U4F4NS6MKN4LWDX74EVRZLUOQS6FQOQKXHIXTY2WXH2===",
                "retain": true
              }'
    
    RetrieveRQ rq = new RetrieveRQ 
    {
      token = "K7WMBFTB5VAQPJWVHBZLFQWCPAYQAQWWS5U4F4NS6MKN4LWDX74EVRZLUOQS6FQOQKXHIXTY2WXH2===",
      retain = true
    }
    
    using (var content = new StringContent(JsonConvert.SerializeObject(rq), System.Text.Encoding.UTF8, "application/json"))
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.swappt.com/v1/organizations/test/retrieve");
      request.Headers.Add("Authorization", "ApiKey YourApiKey");
      request.Content = content;
    }
    

    This method will return the information associated to a token. Moreover, if you wish the data to remain saved, you should set the retain field to True.

    RetriveRQ

    RetriveRQ example

    {
      "token": "K7WMBFTB5VAQPJWVHBZLFQWCPAYQAQWWS5U4F4NS6MKN4LWDX74EVRZLUOQS6FQOQKXHIXTY2WXH2===",
      "retain": true
    }
    
    Attribute Type Description
    token String Token with the information to retrieve.
    retain Boolean True if data must remain saved, False if don't (Default: False).

    RetriveRQ

    RetrieveRS example

    {
      "data": { ... },
      "token": "POYSIGHFLRA7XO64XIFUFUEB3PHCABVZE63ATEWBV6VV6UTL6EJU34I2KOP4N4CB6QM2FJODUK4A4===",
      "status": "Success"
    }
    
    Attribute Type Description
    data String Token with the information to retrieve.
    token String Generated card data token. This field will only be returned if the field retain was sent, and its value was true. Other input will cause the data to be invalidated after returning it.
    status String Response status.

    Appendix

    Additional data types

    In this section you can find an extended explanation of the different enumerated types that the API has.

    PaymentMethodType

    Values
    Visa Hiper Discover Paysafecard
    Mastercard Sofort Trustly Offline_transfer
    American_express Paga_mas_tarde Instant_credit Cetelem
    JCB Klarna Paypal Masterpass
    Union_pay Safety_pay IUPay Multibanco
    Diners_club Braspag Limonetik Cash

    EndTransactionType

    Value Description
    Success The request was processed sucessfully.
    Error There was an error during the process.

    CardInfoType

    Value Description
    Explicit Card info comes raw.
    Encrypted Card info comes encrypted.
    Tokenized Card info comes tokenized.

    ToolCode

    Value
    Protect
    Sift_science

    ModuleType

    Value Description
    ByDecision Indicates that rule should be based on Decision.
    ByScoring Indicates that rule should be based on Score.

    ModuleDecision

    Value
    Accept
    Review
    Reject
    NotConclusive

    GlobalDecision

    Value
    Accept
    Reject
    AcceptWithSecurePayment

    TransactionType

    Value
    Final
    Expirable

    TransactionStatus

    Value
    Success
    Cancel
    Pending
    Received
    Refunded

    PendingReason

    Value Description
    PendingCredit Pending of getting credit.
    PendingCapture Payment is pending of being captured.
    PendingVerification Payment is pending of being verificated for the gateway.

    SearchType

    Value Description
    ByTransaction Search must be done by transaction_id (transaction_id node MUST be specified).
    ByDates Search must be done by date ranges (transaction_start_time and transaction_end_time nodes MUST be specified).

    TriggerType

    Value Description
    manual The decision was taken by a analyst (an anayst id would be indicated on the decision).
    automatic The decision was taken by an automatic system.
    chargeback The decision was taken caused by a chargeback.

    DecisionType

    Value Description
    bad The decision is used to notification that a user or payment is fraudulent.
    warning The decision is used to notification that a user or payment can be fraudulent.
    ok The decision is used to notification that a user or a payment is not fraudulent.

    Fraud Tools responses

    Here you can find explained the responses that the tools can return.

    Protect

    Protect response example

    {
        "result" : "Reject",
        "toolsResults" : {
            "Protect" : {
                "status" : "Reject",
                "transaction_id" : "10d34b7f87974c66847720b871529555",
                "score" : 100,
                "profile_id" : "62",
                "rule_id" : "134",
                "conditions" : [
                    "358"
                ],
                "values" : {
                    "buyer_age_test" : "13"
                },
                "error" : null
            }
        }
    }
    
    Attribute Type Description
    status String(ModuleDecision) The analysis result.
    transactionID String Generated card data token. This field will only be returned if the field retain was sent, and its value was true. Other input will cause the data to be invalidated after returning it.
    score Integer Status in form of score (100-Reject, 50-Review, 0-Accept)
    reason String Deeper description explaining the result.
    profileID String The profile that matched the transaction.
    ruleID String The rule that triggered the result.
    conditionIDs Array[ String ] List of condition ids that where on the triggered rule.
    values Key-Value The list of field ids appearing in the conditions with its values for this transaction.

    ErrorDetails

    Error example:

    {
      "error_details": {
        "error_type": "Fraud",
        "error_messages": [
          {
            "code": "404",
            "description": "Missing field",
            "field": "ip_address"
          }
        ]
      },
      "status": "Error"
    }
    
    Attribute Type Description
    error_type String(SolutionCode) Determines the SWAPPT Solution where the error was caused (FDS, Switcher, Vault), or Technical in case of internal error.
    error_messages Array[GlobalError] List of error descriptions.

    GlobalError contains a deeper description of the error, and follows a simple structure:

    Attribute Description
    code The error code (detailed on error codes section).
    description Provides a textual description of the error cause.
    field Contains the field that is related to the error (for example in 400’s errors).
    process_moment Says when the error was produced (BeforeCallProvider, WhileCallingProvider, AfterCallProvider), which will help us to detect the error and will tell you if the provider method was done.

    Errors

    Error Code Meaning
    400 Bad Request -- YRequest does not match the specification.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- User is not authorized.
    404 Not Found -- The resource could not be found.
    408 RequestTimeout -- Timeout (tipically on provider’s side).
    409 Conflict -- Conflict with the configuration (e.g. FDS returns SecurePayment and referencing a non secure gateway).
    410 Gone -- The resource has been removed from our servers.
    500 Internal Server Error -- We had a problem with our server. Try again later.