Program Registration Tutorial

Overview

In order to register for a program, the basic process is:

1. Start program offering registration (this adds an offering to the cart for a given member)
2. Collect required information such as agreement acceptance or custom questions
3. Repeat step 1 for another offering or member (optional)
4. Collect payment information (if payment is required)
5. Check out

Concepts

• A cart is a temporary storage mechanism for purchasing multiple things and checking out/paying once.
• A product bundle represents a product that is being purchased. For example, if you are registering your 3 children for different programs at the same time, there would be 3 product bundles: 1 for each child.
• A product bundle generates 1 or more line items. For example, a product bundle for a traditional program offering might generate 1 registration fee, and 2 segment fees for a total of 3 line items associated with this product bundle.

Question: Why is it called a product bundle? Why not just call it a registration?

Answer: The cart concept will be used to purchase any item as functionality expands

Full Example

Step 1: Find Program

Use the Programs API calls to find a program to register for and the Units API call to find the member.

The information you need in order to register for a program is:

• program_id
• offering_id
• location_id
• member_id

Step 2: Create a cart

Use the Create a Cart API call to create a new cart. This “Create a Cart” call is exclusive to programs, packages, child care and camp. If attempting to create a cart for Member Join, please reference the Member Join Tutorial.

NOTE: In this example, we are only registering for 1 offering, so this create a cart call is only called once. If you were adding multiple offerings to the cart, you would still only call this once.

Request:

POST /v3/carts

Response:

{
  "cart_id": "d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc"
}

The cart_id in the response is the value you will use on subsequent calls.

Step 3: Start program offering registration

Use the Start Program Offering Registration API call to start the process for an offering.

Request:

POST /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/offerings
{
    "program_id": "TMP1234",
    "offerings": [{
         "offering_id": "SES5678",
         "location_id": "B999"
    }],
    "member_id": "10000-01",
    "registration_type": "online",
    "dry_run": false
}

Response:

{
  "success": true,
  "product_bundle_id": "ee8b0997-9861-4302-a0bf-f8f68fc50522",
  "info": {
    "steps": {
      "required": [
        "instances",
        "questions",
        "agreements",
        "review"
      ]
    },
    "products": [
      {
        "id": "TMP1234",
        "name": "My Program",
        "children": [
          {
            "id": "SES5678",
            "name": "Session #1"
          }
        ]
      }
    ],
    "person": {
      "id": "10000-01",
      "full_name": "Johnny Doe"
    }
  },
  "links": [
    {
      "rel": "instances",
      "href": "/v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/instances"
    }
  ]
}

• The product_bundle_id in the response will be used on subsequent calls to build up the product_bundle (registration) before it is fully added to the cart and available for checkout.

The info.steps.required property returns which steps are needed in order to check out. In this case, the instances step needs to be completed, and the API URL for the instances step is returned in the links property.

Step 4: Choose Instances

Use the cart_id and product_bundle_id in the Get Possible Instances to Register For API call to get a list of instances to choose.

Request:

GET /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/instances

Response:

{
  "info": ...,
  "program": {
    "id": "TMP1234",
    "type": "standard",
    "name": "My Program"
  },
  "instances": [
    {
      "id": "54d590a7-8909-4a58-a056-42afc408f352",
      "name": "",
      "start_date": "2050-01-01T00:00:00.0000000",
      "end_date": "2050-12-31T00:00:00.0000000",
      "due_date": "2050-01-01T00:00:00.0000000",
      "enabled": true,
      "selected": true,
      "amount": 100,
      "waiting_list": false,
      "offering": {
        "id": "SES5678",
        "name": "Session #1"
      },
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 10,
          "percent": 0.1
        }
      ]
    },
    {
      "id": "64d590a7-8909-4a58-af56-42afc408fabc",
      "name": "",
      "start_date": "2050-01-01T00:00:00.0000000",
      "end_date": "2050-12-31T00:00:00.0000000",
      "due_date": "2050-01-01T00:00:00.0000000",
      "enabled": true,
      "selected": true,
      "amount": 150,
      "waiting_list": false,
      "offering": {
        "id": "SES5678",
        "name": "Session #2"
      },
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 15,
          "percent": 0.1
        }
      ]
    }
  ],
  "fees": [
    {
      "type": "reg_fee",
      "name": "Registration Fee",
      "amount": 5.75
    }
  ]
}

If you want to register for “Session #1” and “Session #2”, then get each id from the instances collection that you want to register for and pass to the Choose Instances to Register For API call.

Request:

PUT /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/instances
{
    "instances": [
      { "id": "54d590a7-8909-4a58-a056-42afc408f352" },
      { "id": "64d590a7-8909-4a58-af56-42afc408fabc" }
    ]
}

Response:

{
  "success": true,
  "info": ...,
  "links": [
    {
      "rel": "agreements",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/agreements"
    },
    {
      "rel": "questions",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/questions"
    },
    {
      "rel": "review",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3"
    }
  ]
}

Step 5: Questions

This step is required only when info.steps.required from the step 4 response contains questions (which means that the program setup contains definitions of custom questions).

First, use the Get Questions API call to get a list of custom questions that are set up on the product bundle.

Request:

GET /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/questions

Response:

{
  ...
  "mode": "create",
  "questions": {
    "sect_program_58883": {
      "type": "section",
      "title": "This is the first section of questions",
      "description": "These are the instructions"
    },
    "program_mediumtext-213704": {
      "type": "text",
      "title": "What color is the sky?",
      "description": "",
      "required": false,
      "read_only": false,
      "max_length": 50
    },
    "program_phone-213705": {
      "type": "phone",
      "title": "What is your phone number?",
      "description": "",
      "required": false,
      "read_only": false,
      "show_extension": true,
      "intl": false
    },
    "program_answerlist-213706": {
      "type": "dropdown",
      "title": "What is your favorite letter?",
      "description": "",
      "required": false,
      "read_only": false,
      "possible_answers": [
        {
          "id": "program_possible_answer-104587",
          "value": "A",
          "display_value": "A"
        },
        {
          "id": "program_possible_answer-104588",
          "value": "B",
          "display_value": "B"
        },
        {
          "id": "program_possible_answer-104589",
          "value": "C",
          "display_value": "C"
        }
      ],
      "hide_empty_option": false,
      "empty_value": ""
    },
    "program_answerlist-213707": {
      "type": "checkboxes",
      "title": "Choose 1 or more options below",
      "description": "",
      "required": false,
      "read_only": false,
      "possible_answers": [
        {
          "id": "program_possible_answer-104590",
          "value": "A",
          "amount": 10,
          "display_value": "A - $10.00"
        },
        {
          "id": "program_possible_answer-104591",
          "value": "B",
          "amount": 20,
          "display_value": "B - $20.00"
        },
        {
          "id": "program_possible_answer-104592",
          "value": "C",
          "amount": 20,
          "display_value": "C - $20.00"
        }
      ],
      "hide_empty_option": false,
      "empty_value": ""
    },
    "program_address-213708": {
      "type": "address",
      "title": "What is your address?",
      "description": "",
      "required": false,
      "read_only": false,
      "intl": false
    },
    "program_answerlist-213709": {
      "type": "radio",
      "title": "What is your favorite letter?",
      "description": "",
      "required": false,
      "read_only": false,
      "possible_answers": [
        {
          "id": "program_possible_answer-104593",
          "value": "A",
          "display_value": "A"
        },
        {
          "id": "program_possible_answer-104594",
          "value": "B",
          "display_value": "B"
        },
        {
          "id": "program_possible_answer-104595",
          "value": "C",
          "display_value": "C"
        }
      ],
      "hide_empty_option": false,
      "empty_value": ""
    },
    "program_datetime-213710": {
      "type": "date",
      "title": "What is your birth date?",
      "description": "",
      "required": false,
      "read_only": false
    },
    "program_email-213711": {
      "type": "email",
      "title": "What is your email address?",
      "description": "",
      "required": false,
      "read_only": false,
      "max_length": 100,
      "pattern": "^\\w+([-+.']\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$"
    },
    "program_name-213712": {
      "type": "name",
      "title": "What is your mother's name?",
      "description": "",
      "required": false,
      "read_only": false,
      "show_first": true,
      "show_middle": false,
      "show_last": true,
      "show_prefix": false,
      "show_suffix": true,
      "required_first": false,
      "required_middle": false,
      "required_last": false,
      "suffixes": [
        {
          "id": "Jr.",
          "value": "Jr."
        },
        {
          "id": "Sr.",
          "value": "Sr."
        },
        {
          "id": "I",
          "value": "I"
        },
        {
          "id": "II",
          "value": "II"
        },
        {
          "id": "III",
          "value": "III"
        },
        {
          "id": "IV",
          "value": "IV"
        },
        {
          "id": "V",
          "value": "V"
        }
      ]
    }
  },
  "answers": {}
}

Next, submit answers to the questions. You will pass in a mapping of the question id to the answers supplied:

Request:

PUT /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/answers
{
  "program_mediumtext-213704": "purple",
  "program_phone-213705": {
    "phone": "555-555-5555",
    "ext": "123"
  },
  "program_answerlist-213706": "program_possible_answer-104589",
  "program_answerlist-213707": [
    "program_possible_answer-104591",
    "program_possible_answer-104592"
  ],
  "program_address-213708": {
    "line1": "111 Some Dr",
    "line2": "Ste 208",
    "city": "Homewood",
    "state": "AL",
    "zip": "35209",
    "country": "US"
  },
  "program_answerlist-213709": "program_possible_answer-104594",
  "program_datetime-213710": "1\/1\/2010",
  "program_email-213711": "me@example.com",
  "program_name-213712": {
    "first": "Sally",
    "last": "Doe",
    "suffix": "III"
  }
}

Step 6: Agreements

This step is required only when info.steps.required from the step 4 response contains agreements (which means that the program setup requires certain agreements to be accepted).

First, use the Get Agreements API call to get a list of the agreements set up on the product bundle.

Request:

GET /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/agreements

Response:

{
  ...
  "agreements": [
    {
      "agreement_id": "W293",
      "title": "Make up policy",
      "body": "I agree that you will forfeit your lesson fee if I do not cancel within 2 hours of class start time.",
      "accepted": false
    },
    {
      "agreement_id": "W297",
      "title": "Consent for emergency medical treatment",
      "body": "I grant authorization to a licensed physician to treat msyelf in case of a medical emergency.",
      "accepted": false
    }
  ]
}

Next, mark the agreements as accepted along with the name of the person digitally signing the agreement:

Request:

PUT /v3/carts/d9e6ddd1-6d99-4623-b44c-cdd9450ed5bc/product_bundles/ee8b0997-9861-4302-a0bf-f8f68fc50522/agreements
{
  "agreement_ids": ["W293", "W297"],
  "signee_name": "John Doe"
}

Step 7: Review

Now that the offering has been fully added to the cart, you can get a list of all of the items in the cart with the Get Cart Details API call.

Request:

GET /v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3

Response:

{
  "version": "AAAAAAmit1o=",
  "line_items": [
    {
      "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
      "product_bundle_id": "ee8b0997-9861-4302-a0bf-f8f68fc50522",
      "type": "inst",
      "description": "(My Branch) My Program - Session #1 - (01/01/50 - 12/31/50)",
      "short_description": "01/01/50 - 12/31/50",
      "level1": "Johnny Doe",
      "level2": "My Program",
      "level3": "My Branch",
      "level4": "Session #1",
      "unit_price": 100,
      "quantity": 1,
      "extended_price": 100,
      "can_remove": true,
      "due_date": "2050-01-01T00:00:00.0000000",
      "min_payment_amount": 100,
      "payment_method_amount": 100,
      "system_credit_amount": 0,
      "scheduled_amount": 0,
      "due_later_amount": 0,
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 10,
          "percent": 0.1
        }
      ]
    },
    {
      "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
      "product_bundle_id": "ee8b0997-9861-4302-a0bf-f8f68fc50522",
      "type": "inst",
      "description": "(My Branch) My Program - Session #2 - (01/01/50 - 12/31/50)",
      "short_description": "01/01/50 - 12/31/50",
      "level1": "Johnny Doe",
      "level2": "My Program",
      "level3": "My Branch",
      "level4": "Session #2",
      "unit_price": 150,
      "quantity": 1,
      "extended_price": 150,
      "can_remove": true,
      "due_date": "2050-01-01T00:00:00.0000000",
      "min_payment_amount": 150,
      "payment_method_amount": 150,
      "system_credit_amount": 0,
      "scheduled_amount": 0,
      "due_later_amount": 0,
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 15,
          "percent": 0.5
        }
      ]
    }
  ],
  "line_item_payments": [
    {
      "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
      "amount": 100,
      "schedule_remaining": true
    },
    {
      "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
      "amount": 150,
      "schedule_remaining": true
    }
  ],
  "promo_codes": [],
  "require_payment_method": true,
  "max_payment_method_amount": 250
}

Step 8a: Checkout (without payment)

In order to checkout without payment, the payment_method_amount must be 0, and each amount in the line_item_payments collection must be 0. The version value must be the same as the last value from the Get Cart Details API call.

Request:

POST /v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/checkout
{
  "version": "AAAAAAmit1o=",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.org"
  },
  "payment_info": [
    {
      "payment_method_amount": 0.0,
      "line_item_payments": [
        {
          "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
          "amount": 0,
          "schedule_remaining": false
        },
        {
          "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
          "amount": 0,
          "schedule_remaining": false
        },
      ]
    }
  ]
}

Response:

{
  "success": true,
  "links": [
    {
      "rel": "receipt",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/receipt"
    },
    {
      "rel": "status",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/status"
    }
  ]
}

Step 8b: Checkout (with Daxko Operations payment page)

This is the preferred method to capture payment information and check out.

Use the Program Registration One-time Link to generate a one-time link (that expires in 10 minutes) that you will redirect your user to Daxko Operations Online in order to capture payment information and complete the checkout process.

Request:

POST /v3/carts/2b8a53f2-d482-40f2-a83a-ee5c4d8d8d94/one_time_link
{
  "redirect_uri": "https://example.org/my_success_landing_page",
  "step": "pay",
  "header": "show",
  "nav": "hide",
  "footer": "hide",
  "customer_name": "John Doe",
  "customer_email": "john.doe@example.org"
}

Response

{
  "url": "https://operations.daxko.com/online/2014/cart/redirector.mvc?code=_qNGKCKowkSmHDzCY6y8zT4bxCCD2LZgQN8m4ko_6E0&__header=show&__footer=hide&__nav=hide"
}

Step 8c: Checkout (with new payment method)

In order to pay with a new payment method, it must be tokenized using our payment tokens JavaScript library. First, see the Payment Tokenization tutorial on how to generate a payment token. The output will be a value that looks like PT3raaMpFPXEsmVexb5JOF3Zpff2TmtENJ_yZkLTudSrY and will be used in the checkout call.

Request:

POST /v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/checkout
{
  "version": "AAAAAAmit1o=",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.org"
  },
  "payment_info": [
    {
      "payment_method_amount": 250,
      "billing_method": {
        "id": "PT3raaMpFPXEsmVexb5JOF3Zpff2TmtENJ_yZkLTudSrY",
        "save": true
      },
      "line_item_payments": [
        {
          "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
          "amount": 150,
          "schedule_remaining": false
        },
        {
          "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
          "amount": 100,
          "schedule_remaining": false
        },
      ]
    }
  ]
}

Declined Response:

{
  "success": false,
  "errors": [
    {
      "message": "Declined"
    }
  ]
}

Successful Response:

{
  "success": true,
  "links": [
    {
      "rel": "receipt",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/receipt"
    },
    {
      "rel": "status",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/status"
    }
  ]
}

Step 8d: Checkout (with existing payment method)

In order to pay with a payment method that exists on the unit’s account: first, use the Get Unit Billing Methods API call:

Request:

GET /v3/units/10000/billing_methods

Response:

{
  "billing_methods": [
    {
      "id": "BM1955320",
      "method": "bank_account",
      "name": "EFT",
      "account_number_last_4_digits": "1111",
      "display_name": "Bank Account (ending in 1111)",
      "expired": false
    }
    {
      "id": "BM1965321",
      "method": "credit_card",
      "name": "MasterCard",
      "account_number_last_4_digits": "5100",
      "display_name": "MasterCard (ending in 5100, expires 1/2022)",
      "expired": false
    }
  ]
}

Now use the id from the previous response in the checkout API call.

Request:

POST /v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/checkout
{
  "version": "AAAAAAmit1o=",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.org"
  },
  "payment_info": [
    {
      "payment_method_amount": 250,
      "billing_method": {
        "id": "BM1965321"
      },
      "line_item_payments": [
        {
          "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
          "amount": 150,
          "schedule_remaining": false
        },
        {
          "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
          "amount": 100,
          "schedule_remaining": false
        },
      ]
    }
  ]
}

Declined Response:

{
  "success": false,
  "errors": [
    {
      "message": "Declined"
    }
  ]
}

Successful Response:

{
  "success": true,
  "links": [
    {
      "rel": "receipt",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/receipt"
    },
    {
      "rel": "status",
      "href": "/v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/status"
    }
  ]
}

Step 9: Receipt

The receipt is available immediately after checkout out, but the registration is written to Daxko Operations asynchronously. You can check the status of the registration being written to Daxko Operations with the Get Cart Status API call.

Request:

GET /v3/carts/aa46bcf4-b65a-4a37-bed9-5dcb4674d0a3/receipt

Response:

{
  "order_date": "2017-10-12T21:06:58.6460000Z",
  "payments": [],
  "line_items": [
    {
      "line_item_id": "aaaaaaaa-0b27-48c7-b682-48e5206e0be3",
      "product_bundle_id": "ee8b0997-9861-4302-a0bf-f8f68fc50522",
      "type": "inst",
      "description": "(My Branch) My Program - Session #1 - (01/01/50 - 12/31/50)",
      "short_description": "01/01/50 - 12/31/50",
      "level1": "Johnny Doe",
      "level2": "My Program",
      "level3": "My Branch",
      "level4": "Session #1",
      "unit_price": 100,
      "quantity": 1,
      "extended_price": 100,
      "due_date": "2050-01-01T00:00:00.0000000",
      "payment_method_amount": 100,
      "system_credit_amount": 0,
      "scheduled_amount": 0,
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 10,
          "percent": 0.1
        }
      ]
    },
    {
      "line_item_id": "bbbbbbbb-0b27-48c7-b682-48e5206e0be3",
      "product_bundle_id": "ee8b0997-9861-4302-a0bf-f8f68fc50522",
      "type": "inst",
      "description": "(My Branch) My Program - Session #2 - (01/01/50 - 12/31/50)",
      "short_description": "01/01/50 - 12/31/50",
      "level1": "Johnny Doe",
      "level2": "My Program",
      "level3": "My Branch",
      "level4": "Session #2",
      "unit_price": 150,
      "quantity": 1,
      "extended_price": 150,
      "due_date": "2050-01-01T00:00:00.0000000",
      "payment_method_amount": 150,
      "system_credit_amount": 0,
      "scheduled_amount": 0,
      "discounts": [
        {
          "type": "schol",
          "name": "Scholarship",
          "amount": 15,
          "percent": 0.5
        }
      ]
    }
  ],
  "customer": {
    "phone": "(999) 123-4567",
    "unit_id": "300181454",
    "purchased_by": "John Doe",
    "email": "john.doe@example.org",
    "name": "Doe, John",
    "address": {
      "line1": "123 Some Dr.",
      "line2": "",
      "city": "Beverly Hills",
      "state": "CA",
      "zip": "90210",
      "country": "US"
    }
  },
  "vendor": {
    "name": "My Branch",
    "address": {
      "line1": "555 My Branch Dr.",
      "line2": "",
      "city": "Beverly Hills",
      "state": "CA",
      "zip": "90210",
      "country": "US"
    },
    "footer": "FOR YOUTH DEVELOPMENT FOR HEALTHY LIVING FOR SOCIAL RESPONSIBILITY",
    "tax_id": "111112222",
    "phone": "(999) 555-5555"
  }
}

Comments